×
INTELLIGENT WORK FORUMS
FOR ENGINEERING PROFESSIONALS

Log In

Come Join Us!

Are you an
Engineering professional?
Join Eng-Tips Forums!
  • Talk With Other Members
  • Be Notified Of Responses
    To Your Posts
  • Keyword Search
  • One-Click Access To Your
    Favorite Forums
  • Automated Signatures
    On Your Posts
  • Best Of All, It's Free!
  • Students Click Here

*Eng-Tips's functionality depends on members receiving e-mail. By joining you are opting in to receive e-mail.

Posting Guidelines

Promoting, selling, recruiting, coursework and thesis posting is forbidden.

Students Click Here

Jobs

Writing a user manual in third person

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

RE: Writing a user manual in third person

"...it rubs the lotion on its skin" Is that better?

If you are offended by the things I say, imagine the stuff I hold back.

RE: Writing a user manual in third person

I'm pretty sure those are personalized instructions, custom made for you. When I open that same file it reads as:

. . . 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

I just wrote a whole book using pronouns and first person. Several (engineer) reviewers had problems with the tone, but the copy editors didn't, in fact one of them thanked me for not making him plow through another lifeless tome. I think the times are changing, and it is about dang time.

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 play this regular game where I get asked to comment on tech support enquiries. I write my findings in the first person: "When I opened this dialog, pressed this button, xyz happened." Then leave it for our customer-facing people to do their preferred pronoun transformation/removal. Depending on who does this, the results can be amusing,to say the least. The message is never lost, just the tone changes.

Steve

RE: Writing a user manual in third person

I'm really puzzled by all this "if it isn't in the 'third person', it's wrong" stuff.

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

zeusfaber,
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

Very poor and lazy writing, amateurish for technical documents. I might just be old fashioned and have retained too much from advanced composition and writing classes, though. My opinion only.

"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

(OP)
Thank you ornerynorsk, my feelings exactly.

Jerry J.
UGV5-NX11

RE: Writing a user manual in third person

(OP)
zdas04, that is risky and lazy writing.
If I had the book it would go in the garbage.

Jerry J.
UGV5-NX11

RE: Writing a user manual in third person

In my opinion taking either style to extremes is bad. Generally technical writing is third person or passive voice because it is meant to be technical and non-emotional / no egoism. But that can make the writing style really boring, and sometimes ridiculous.

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

jerry123,
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

The latest version of Microsoft Word automatically flags anything written in the passive voice. (If there is a way of turning that off, I haven't found it.)

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

Just clicked on browser's help:

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 guess It 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

Fatdad,
Thanks for sharing that. It contains the best example of how not to write I've ever come across:

Quote:

Simians indigenous to Zamboanga are destitute of caudal amenduges.
Which of course means

Spoiler:

Monkeys have no tails in Zamboanga.

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

zdas04,

What's wrong with "Eschew obsfuscation."?

--
JHG

RE: Writing a user manual in third person

I'm impressed. You, your, and you're all used correctly.

RE: Writing a user manual in third person

drawoh,
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

I run all sorts of text through a Fog Index calculator. It's a worthy gauge!

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!

Red Flag This Post

Please let us know here why this post is inappropriate. Reasons such as off-topic, duplicates, flames, illegal, vulgar, or students posting their homework.

Red Flag Submitted

Thank you for helping keep Eng-Tips Forums free from inappropriate posts.
The Eng-Tips staff will check this out and take appropriate action.

Reply To This Thread

Posting in the Eng-Tips forums is a member-only feature.

Click Here to join Eng-Tips and talk with other members!


Resources


Close Box

Join Eng-Tips® Today!

Join your peers on the Internet's largest technical engineering professional community.
It's easy to join and it's free.

Here's Why Members Love Eng-Tips Forums:

Register now while it's still free!

Already a member? Close this window and log in.

Join Us             Close