Understanding points of view in engineering docs

joeliedtke@google.com

What kind of engineering docs do we write?

• Bug reports
• Design specifications
• UX observations
• Technical documentation
• Blog posts

Writing documentation = storytelling

First person point of view

Documentation where the writer shares their experience with the reader.

“I created a PV, then I added it to the Kubernetes cluster...”

Hint: Look for the pronoun I.

​

​

​

Examples:

• Bug reports
• Blog posts

Third person point of view

Documentation where the writer shares someone else’s experience with the reader.

“The user checks that the conda command is available by...”

Hint: Look for the pronouns he, she, it, they, or descriptions of the actor such as “the user.”

Examples:

• Design documentation
• UX observations

Second person point of view

Documentation where the writer speaks directly to the reader.

“Run the following command to install Kubeflow Fairing in your virtual environment.”

Hint: Look for the pronoun you, it may be implied.

​

Examples:

• Technical documentation

​

Be direct...

Please install the SDK.

You should ...

Install the SDK.

You must ...

->

->

Direct communication should be clear and concise.

This business is well ended.�My liege, and madam, to expostulate�What majesty should be, what duty is,�Why day is day, night night, and time is time,�Were nothing but to waste night, day and time.�Therefore, since brevity is the soul of wit,�And tediousness the limbs and outward flourishes,�I will be brief: your noble son is mad:�Mad call I it; for, to define true madness,�What is't but to be nothing else but mad?�But let that go.

- Polonius, a long-winded person, Hamlet, William Shakespeare

​

​

Hamlet is insane

Avoid making yourself an active participant

• Be careful when using let’s, us, we, or our.
• Let’s install kubectl. == Let us install kubectl.
• If we're deleting multiple entries at a time …

​

​

Pronouns

The name of the function to execute in the given script. It does not include parentheses or parameters.

The name of the function to execute in the given script. The name does not include parentheses or parameters.

If the code changes look good to them, a reviewer types /lgtm in a PR comment or review; if they change their mind, they /lgtm cancel

• Ensure that pronouns have clear antecedents
• Do not use gender-specific pronouns when referring to the reader.
• Only use gender-specific pronouns when writing about an actual person. In that case use the person’s preferred pronouns.
• Use the singular “they” if you need a pronoun to refer to a generic person.
• For example, when referring to a “Kubeflow contributor” or “reviewer,” use “they” if you need to use a pronoun.

References

• Kubeflow Style Guide
• Address the audience directly
• Google Developer Documentation Style Guide
• Second person and first person
• Pronouns

​

​

Thank you!

Any questions?

joeliedtke@google.com