Writing a user manual in third person
Writing a user manual in third person
(OP)
What happened to writing in third person and avoiding pronouns ?
Below is some documentation I clipped from on-line help for the CAD software that I have spent most of my career on.
Previously very skilled people wrote their documentation, but with new releases it seems like some high school kids are doing their work.
. . . opens the Settings dialog box and lets you change the display of the 2D component instances you are placing. This affects only the settings of 2D component you place while the Insert 2D Component dialog box is open. When you close the dialog box or if you launch another command, the settings return to their default values.
I guess I am suppose to imagine the manual is speaking to me, and referring to me as "you".
This is quite upsetting because I was taught in college never to write like this.
Why is this now acceptable writing ?
Jerry J.
UGV5-NX11
Below is some documentation I clipped from on-line help for the CAD software that I have spent most of my career on.
Previously very skilled people wrote their documentation, but with new releases it seems like some high school kids are doing their work.
. . . opens the Settings dialog box and lets you change the display of the 2D component instances you are placing. This affects only the settings of 2D component you place while the Insert 2D Component dialog box is open. When you close the dialog box or if you launch another command, the settings return to their default values.
I guess I am suppose to imagine the manual is speaking to me, and referring to me as "you".
This is quite upsetting because I was taught in college never to write like this.
Why is this now acceptable writing ?
Jerry J.
UGV5-NX11





RE: Writing a user manual in third person
If you are offended by the things I say, imagine the stuff I hold back.
RE: Writing a user manual in third person
. . . opens the Settings dialog box and lets Jerry change the display of the 2D component instances Jerry is placing. This affects only the settings of 2D component Jerry places while the Insert 2D Component dialog box is open. When Jerry closes the dialog box or if Jerry launches another command, the settings return to their default values.
Joking aside, it is a shift in professional culture. It might get squashed and things will go back to normal, but I wouldn't be surprised to see more of this style in the future and more attempts at making it the norm.
Andrew H.
www.mototribology.com
RE: Writing a user manual in third person
David Simpson, PE
MuleShoe Engineering
In questions of science, the authority of a thousand is not worth the humble reasoning of a single individual. Galileo Galilei, Italian Physicist
RE: Writing a user manual in third person
Steve
RE: Writing a user manual in third person
Not so much about the way the documents are written - which is, after all, a style choice...
...but more about why people call it "writing in the third person".
We're not talking about replacing "When I opened this dialog..." with "When ze/she/he opened this dialog"....
The formula we're getting wound up about is "When this dialog was opened..." - which is surely a statement in the passive voice, rather than the third person.
If people are going to be such pedants, can't they at least make some effort to do it properly?
A.
RE: Writing a user manual in third person
You are absolutely correct, it is passive voice, and it tends to be bland and not-engaging.
David Simpson, PE
MuleShoe Engineering
In questions of science, the authority of a thousand is not worth the humble reasoning of a single individual. Galileo Galilei, Italian Physicist
RE: Writing a user manual in third person
"opens the Settings dialog box and lets you change the display of the 2D component instances you are placing. This affects only the settings of 2D component you place while the Insert 2D Component dialog box is open. When you close the dialog box or if you launch another command, the settings return to their default values."
Or instead ~ "opens the Settings dialog box and allows change of the display of the 2D instances being placed. This affects only those settings while dialog box is open. Settings return to default values once dialog box is closed or another command is launched."
It is better to have enough ideas for some of them to be wrong, than to be always right by having no ideas at all.
RE: Writing a user manual in third person
Jerry J.
UGV5-NX11
RE: Writing a user manual in third person
If I had the book it would go in the garbage.
Jerry J.
UGV5-NX11
RE: Writing a user manual in third person
Kind of like Winston Churchill's example of not ending a sentence with a preposition:
"Ending a sentence with a preposition is something up with which I will not put."
RE: Writing a user manual in third person
Then you probably shouldn't buy it. The comments I've received from people who did buy it have been positive, but I would expect that my style is not for everyone.
David Simpson, PE
MuleShoe Engineering
In questions of science, the authority of a thousand is not worth the humble reasoning of a single individual. Galileo Galilei, Italian Physicist
RE: Writing a user manual in third person
I've been very annoyed by it, because the main alternative is to write in the manner you find objectionable. I wonder if this new feature (I'm sure introduced by English majors...) has anything to do with the trend you are noticing.
RE: Writing a user manual in third person
https://res.cloudinary.com/engineering-com/image/upload/v1518551474/tips/Improve_Your_Writing_-_Dept._of_the_Army_Pamphlet_y3wjgv.pdf
Let's see if the upload works?
f-d
ípapß gordo ainÆt no madre flaca!
RE: Writing a user manual in third person
If you're seeing some of these problems with Chrome, you might have unwanted software or malware installed on your computer:[highlight
Pop-up ads and new tabs that won't go away.
Your Chrome homepage or search engine keeps changing without your permission.
Unwanted Chrome extensions or toolbars keep coming back.
Your browsing is hijacked, and redirects to unfamiliar pages or ads.
Alerts about a virus or an infected device.
Here are some steps you can take to get rid of unwanted software. In the future, avoid unwanted software by only downloading files or visiting sites that you know are secure.
I guessIt is guessed the beast is out. The Internet generation will never look back"For every expert there is an equal and opposite expert"
Arthur C. Clarke Profiles of the future
RE: Writing a user manual in third person
Thanks for sharing that. It contains the best example of how not to write I've ever come across:
Which of course means
Spoiler:
David Simpson, PE
MuleShoe Engineering
In questions of science, the authority of a thousand is not worth the humble reasoning of a single individual. Galileo Galilei, Italian Physicist
RE: Writing a user manual in third person
What's wrong with "Eschew obsfuscation."?
--
JHG
RE: Writing a user manual in third person
RE: Writing a user manual in third person
The fine document that FatDad shared explains that quite well. The "Fog Index" would downcheck the second word for being too long. I ran my book through an online Fox Index calculator and got an average score of 14.5 (anything higher than 12 is not suitable for non-technical audiences), I wonder what it would be if I hadn't carefully worked to avoid the passive voice and had eliminated personal pronouns.
David Simpson, PE
MuleShoe Engineering
In questions of science, the authority of a thousand is not worth the humble reasoning of a single individual. Galileo Galilei, Italian Physicist
RE: Writing a user manual in third person
In the words of my father, "Don't use the word utilize, utilize the word use."
f-d
ípapß gordo ainÆt no madre flaca!