| View previous topic :: View next topic |
| Author |
Message |
myga
Tux's lil' helper
Joined: 12 Jun 2023
Posts: 99
|
 Posted: Fri Jan 26, 2024 4:57 am Post subject: Gentoo Wiki:Guidelines - an oopsie |
 |
|
I was reading the Gentoo Wiki:Guidelines and the following section made me laugh:
| Quote: | Avoid first and second person writing
Since the wiki is a community-effort and the content pages are informational, there should be no mention of pronouns such as "I", "we", or "you". Articles should be written in third person: reported as a fact to the reader.
Third person and passive voice are preferred[1]; we argue these sound more professional and objective; especially for technical instructions, which is the majority of the wiki's content. |
Let's see if you can guess what is wrong here. |
|
| Back to top |
|
 |
GDH-gentoo
Veteran
Joined: 20 Jul 2019
Posts: 1537
Location: South America
|
| Posted: Fri Jan 26, 2024 12:23 pm Post subject: Re: Gentoo Wiki:Guidelines - an oopsie |
|
|
| myga wrote: | | Let's see if you can guess what is wrong here. |
Nothing  The guidelines article is an exception to the rule and second person in that paragraph is justified.
_________________
| NeddySeagoon wrote: | | I'm not a witch, I'm a retired electronics engineer |
| Ionen wrote: | | As a packager I just don't want things to get messier with weird build systems and multiple toolchains requirements though |
|
|
| Back to top |
|
|
eeckwrk99
Apprentice
Joined: 14 Mar 2021
Posts: 163
Location: Gentoo forums
|
| Posted: Fri Jan 26, 2024 1:07 pm Post subject: Re: Gentoo Wiki:Guidelines - an oopsie |
|
|
| GDH-gentoo wrote: | | myga wrote: | | Let's see if you can guess what is wrong here. |
Nothing The guidelines article is an exception to the rule and second person in that paragraph is justified. |
Agreed. There's nothing wrong. |
|
| Back to top |
|
|
Goverp
Advocate
Joined: 07 Mar 2007
Posts: 2009
|
| Posted: Fri Jan 26, 2024 1:29 pm Post subject: |
|
|
I'm amazed third person passive voice is recommended. Every other recommendation I've seen for documentation goes for 2nd person active - "Press the red button; Stand clear; Wait for the kaboom." rather than "The red button is pressed. The operator stands clear. The kaboom is awaited".
The trouble with passive voice is that it's not clear who does what; usually for software there's just one user so there's no ambiguity, but in client-server discussions, passive voice is a real pain. "The file is requested from one of the servers. The file server is started. The file is sent." It's not clear in this example who/what starts the file server - it might be by the system in response to the request, or by the user as part of the procedure.
As for second person, it's shorter, and leads to more understandable instructions. It also avoids any argument, at least in English, over gender/preferred pronouns.
"Insert the diskette. Start the liquidizer" vs "The user inserts the diskette. He/she/they start the liquidizer"
For those in more need, I've corrected the original instruction:
| Quote: | Writing in first and second person should be avoided.
Since the wiki is a community-effort and the content pages are informational, there should be no mention of pronouns such as "I", "we", or "you". Articles should be written in third person: reported as a fact to the reader.
Third person and passive voice are preferred[1]; it is argued that these sound more professional and objective; especially for technical instructions, which is the majority of the wiki's content. |
And of course, without following the reference (which I can't do as it's not a link here), I don't know whose preference this is, no whose arguments (and whether or not they are the same people).
I prefer:
| Quote: | Write in second or third person.
Present Information in third person: as a fact to the reader; procedures should be in second person: as instructions.
Prefer second or third person and active voice. |
_________________
Greybeard |
|
| Back to top |
|
|
GDH-gentoo
Veteran
Joined: 20 Jul 2019
Posts: 1537
Location: South America
|
| Posted: Fri Jan 26, 2024 2:50 pm Post subject: |
|
|
| Goverp wrote: | | And of course, without following the reference (which I can't do as it's not a link here), I don't know whose preference this is, no whose arguments (and whether or not they are the same people). |
Actually, the reference, which I only bothered reading now (), seems to agree with you:
| Quote: | <<In the past I have written using second person because I wrote for my team members or individual users. Now I have an official tech writing position and I am unsure of which perspective to use. Third person sounds so stiff, but is it more professional?>>
Second person works best in many cases because it allows the use of the imperative voice: "Do this, then do that, then be glad you didn't lose any fingers." It's concise, focuses on the reader, and is generally quite effective... which is why it's becoming standard practice.
Of course, this is an example of where you're telling the reader to do something. When you're not, second person isn't necessary and may even be inappropriate. Consider, for example, how natural it is to say the following: "Gloves less than 2 inches thick won't protect your fingers." You could say "Wear gloves at least 2 inches thick...", but if you're describing a situation rather than telling someone to do something, second person isn't necessary.
Third person is generally less effective because it is more verbose and in some styles, distances the reader from the action. "Chainmail gloves should be worn" offers no benefits over "wear chainmail gloves--or else", and sets up an odd dynamic: "We're talking about the reader; if we had meant _you_, we'd have said _you_, so get over yourself already". That's why you find it "stiff". Moreover, using third person often (as in my example at the start of this paragraph) leads to inappropriate use of passive voice. Passive voice is inappropriate if it leaves the actor implicit when the actor should be explicitly identified. "The gloves should be worn" suggests, but does not make it clear, that you, the reader, should be the one who wears the gloves.
Third person is, of course, perfectly appropriate when you want to focus on "he or she or they" or "him, her, or them". For example: "After you install Microsoft FingerMangler(R), instruct users to wear gloves at all times. They must not use this evil device barehanded--we can attest to this from firsthand experience." |
_________________
| NeddySeagoon wrote: | | I'm not a witch, I'm a retired electronics engineer |
| Ionen wrote: | | As a packager I just don't want things to get messier with weird build systems and multiple toolchains requirements though |
|
|
| Back to top |
|
|
mrbassie
l33t
Joined: 31 May 2013
Posts: 772
Location: over here
|
| Posted: Fri Jan 26, 2024 6:20 pm Post subject: |
|
|
Amusingly, (see what I did there boys and girls?) already solved
EDIT: WHOOOOooPS, missed the question you see. Depending entirely on which actual type of fish the intended catch, it would either be this bit "we argue these sound more professional and objective" or... one of the other ones.
_________________
Bus conductors learned to code. |
|
| Back to top |
|
|
wjb
l33t
Joined: 10 Jul 2005
Posts: 609
Location: Fife, Scotland
|
| Posted: Fri Jan 26, 2024 7:52 pm Post subject: |
|
|
| Writing s/w docs (in the UK), 3rd person was generally what was required. Grammar checkers hated it, but reviewers got really tetchy if not used. |
|
| Back to top |
|
|
Fitzcarraldo
Advocate
Joined: 30 Aug 2008
Posts: 2034
Location: United Kingdom
|
| Posted: Fri Jan 26, 2024 8:34 pm Post subject: |
|
|
| Goverp wrote: | I'm amazed third person passive voice is recommended. Every other recommendation I've seen for documentation goes for 2nd person active - "Press the red button; Stand clear; Wait for the kaboom." rather than "The red button is pressed. The operator stands clear. The kaboom is awaited".
The trouble with passive voice is that it's not clear who does what; usually for software there's just one user so there's no ambiguity, but in client-server discussions, passive voice is a real pain. "The file is requested from one of the servers. The file server is started. The file is sent." It's not clear in this example who/what starts the file server - it might be by the system in response to the request, or by the user as part of the procedure.
As for second person, it's shorter, and leads to more understandable instructions. It also avoids any argument, at least in English, over gender/preferred pronouns.
"Insert the diskette. Start the liquidizer" vs "The user inserts the diskette. He/she/they start the liquidizer"
For those in more need, I've corrected the original instruction:
| Quote: | Writing in first and second person should be avoided.
Since the wiki is a community-effort and the content pages are informational, there should be no mention of pronouns such as "I", "we", or "you". Articles should be written in third person: reported as a fact to the reader.
Third person and passive voice are preferred[1]; it is argued that these sound more professional and objective; especially for technical instructions, which is the majority of the wiki's content. |
And of course, without following the reference (which I can't do as it's not a link here), I don't know whose preference this is, no whose arguments (and whether or not they are the same people).
I prefer:
| Quote: | Write in second or third person.
Present Information in third person: as a fact to the reader; procedures should be in second person: as instructions.
Prefer second or third person and active voice. |
|
I agree fully with you. And, as far as the passive voice is concerned, in my career I have always avoided using the passive voice in the user guides, technical reports, specifications, design briefs, etc. that I have authored. I remember reading a good book in my youth about technical writing that recommended not using the passive voice, and that always stuck with me. There are quite a few books on technical writing, including the following free, downloadable edition:
https://openoregon.pressbooks.pub/technicalwriting/
| Quote: | | In instructions, for example, using imperative voice and “you” phrasing is vastly more understandable than the passive voice or third-personal phrasing. For some reason, personalizing your writing style and making it more relaxed and informal can make it more accessible and understandable. Passive, person-less writing is harder to read—put people and action in your writing. |
_________________
Clevo W230SS: amd64, VIDEO_CARDS="intel modesetting nvidia".
Compal NBLB2: ~amd64, xf86-video-ati. Dual boot Win 7 Pro 64-bit.
OpenRC udev elogind & KDE on both.
Fitzcarraldo's blog |
|
| Back to top |
|
|
szatox
Advocate
Joined: 27 Aug 2013
Posts: 3138
|
| Posted: Fri Jan 26, 2024 9:40 pm Post subject: |
|
|
The funny thing is it doesn't really matter.
The important part of creating any kind of content is "don't waste peoples' time". You can give it any style you find convenient for getting your point across. Active, passive, aggressive, dry, funny, whatever. As long as the things you're writing are relevant, organized, understandable and actually helpful, it's good.
What's appropriate or not is a matter of feelings; you'll never satisfy everybody, so might just as well not worry about it. If you're trying to share information, just focus on that information.
People looking for that information will appreciate that you did, whether you sound professional or cheeky.
_________________
Make Computing Fun Again |
|
| Back to top |
|
|
spica
Apprentice
Joined: 04 Jun 2021
Posts: 287
|
| Posted: Fri Jan 26, 2024 10:55 pm Post subject: |
|
|
In response to the user's amusement at tech docs written in 3rd person passive voice, one could playfully suggest, "It seems like the documentation is aspiring to be the Shakespeare of the tech world - you know, adding a touch of drama and mystery! Who knew coding could be so theatrical?"
On the Gentoo Wiki, the guide elucidates the process of constructing a personalized Linux "lego" game. The use of the pronoun "you" is suitable in this context as it addresses a singular user typically lacking prior experience, seeking assistance on the other side of the screen. However, it's noteworthy that contemporary intricate technologies are typically conveyed through verbs, highlighting processes that transform object A into object B. The emphasis is on the actions of the technology itself rather than instructing the user on specific manual steps. This approach avoids detailing what a person must do with their left or right hand, focusing more on the overall process of transformation. |
|
| Back to top |
|
|
pietinger
Moderator
Joined: 17 Oct 2006
Posts: 4160
Location: Bavaria
|
| Posted: Sat Jan 27, 2024 3:35 am Post subject: |
|
|
| szatox wrote: | | [...] The important part of creating any kind of content is "don't waste peoples' time". [...] As long as the things you're writing are relevant, organized, understandable and actually helpful, it's good. |
++
I hate writing in the third person ... for one simple reason: when I recommend something, it is by no means a consolidated opinion of all gentoo developers. If I were to write this in the third person, it might give that impression. If I recommend something then I have to stand by it; I would consider it cowardly to write it in the third person. I also really like to write the way I would speak to someone ... it's more personal and friendly for me. I understand that, from the point of view of exchanging information as objectively as possible, it should be avoided as far as possible to exclude any personal opinion. But that makes it impersonal and "cold" for me. That's why I prefer to write here in the forum and won't write articles in the wiki (except my personal ones, where I don't have to stick to this rule).
_________________
https://wiki.gentoo.org/wiki/User:Pietinger |
|
| Back to top |
|
|
sam_
Developer
Joined: 14 Aug 2020
Posts: 1678
|
| Posted: Sat Jan 27, 2024 7:06 am Post subject: |
|
|
| wjb wrote: | | Writing s/w docs (in the UK), 3rd person was generally what was required. Grammar checkers hated it, but reviewers got really tetchy if not used. |
Yep, same here. I don't like it, but a consistent style has its value too. |
|
| Back to top |
|
|
Goverp
Advocate
Joined: 07 Mar 2007
Posts: 2009
|
| Posted: Sat Jan 27, 2024 11:15 am Post subject: |
|
|
| wjb wrote: | | Writing s/w docs (in the UK), 3rd person was generally what was required. Grammar checkers hated it, but reviewers got really tetchy if not used. |
A different part of the UK: my experience was writing s/w docs for IBM in the UK, and AFAIR their requirement was 2nd person active.
_________________
Greybeard |
|
| Back to top |
|
|
Goverp
Advocate
Joined: 07 Mar 2007
Posts: 2009
|
| Posted: Sat Jan 27, 2024 11:36 am Post subject: |
|
|
| Goverp wrote: | ...
my experience was writing s/w docs for IBM in the UK, and AFAIR their requirement was 2nd person active. |
To bend to a different fork, one of my favourite IBM documentation features, at least in the early days, was the arrangement into a specific set of manuals:
- General Information - why you'd buy or use it, features and advantages
- Concepts and Facilities - the philosophy behind its design
- User Guide - use cases and how to address them
- User Reference - usually an alphabetical list of commands, their parameters and their effects
For example, for SQL you might write:
| Quote: | SQL provides an easy to use and understand standardised language for interacting with relational databases, allowing you to use the same procedures with diverse database products.
SQL reflects the structures of a relational database - tables, keys, fields, views, and lets you write and store parametrised procedures that manipulates these structures from a program using the paramaters to tailor the procedure for a particular result.
To produce a report, use the SELECT (foo, bah) FROM table WHERE condition; To update a table use INSERT INTO table ...
Command DELETE table
Command INSERT
INTO table
Command SELECT
FROM table|view...
WHERE condition |
It's quite a good chapter structure for any documentation.
_________________
Greybeard |
|
| Back to top |
|
|
Naib
Watchman
Joined: 21 May 2004
Posts: 6051
Location: Removed by Neddy
|
| Posted: Sat Jan 27, 2024 12:25 pm Post subject: Re: Gentoo Wiki:Guidelines - an oopsie |
|
|
| myga wrote: | I was reading the Gentoo Wiki:Guidelines and the following section made me laugh:
| Quote: | Avoid first and second person writing
Since the wiki is a community-effort and the content pages are informational, there should be no mention of pronouns such as "I", "we", or "you". Articles should be written in third person: reported as a fact to the reader.
Third person and passive voice are preferred[1]; we argue these sound more professional and objective; especially for technical instructions, which is the majority of the wiki's content. |
Let's see if you can guess what is wrong here. |
Then update it, that's the point of a wiki. My recommendation would be this:
| Quote: | Avoid first and second person writing
Since the wiki is a community-effort and the content pages are informational, there should be no mention of pronouns such as "I", "we", or "you". Articles should be written in third person: reported as a fact to the reader.
Third person and passive voice are preferred[1]; it is perceived this sounds more professional and objective; especially for technical instructions, which is the majority of the wiki's content. |
_________________
| Quote: | | Removed by Chiitoo |
|
|
| Back to top |
|
|
szatox
Advocate
Joined: 27 Aug 2013
Posts: 3138
|
| Posted: Sat Jan 27, 2024 1:07 pm Post subject: |
|
|
| Quote: | | I also really like to write the way I would speak to someone ... it's more personal and friendly for me. I understand that, from the point of view of exchanging information as objectively as possible, it should be avoided as far as possible to exclude any personal opinion. |
I don't. Sounding objective and being objective are 2 different things.
One is style, the other is perspective. You can write in a very friendly and personal way and offer a good take on a subject, just like you can expertly present your opinion as a statement of fact. MDM (main drain media) do that all the time.
| Goverp wrote: |
| wjb wrote: |
Writing s/w docs (in the UK), 3rd person was generally what was required. Grammar checkers hated it, but reviewers got really tetchy if not used.
|
A different part of the UK: my experience was writing s/w docs for IBM in the UK, and AFAIR their requirement was 2nd person active.
|
There is a pretty big difference between working for a paycheck and volunteering though.
When a company contracts you to do stuff by their standards, said standards are a part of that contract. Volunteering, you have much more authority over your standards.
_________________
Make Computing Fun Again |
|
| Back to top |
|
|
|
|
You cannot post new topics in this forum
You cannot reply to topics in this forum
You cannot edit your posts in this forum
You cannot delete your posts in this forum
You cannot vote in polls in this forum
|
|
Gentoo Chat
