User:SPage (WMF)/On tech writing

See also www.mediawiki.org's Documentation/Style guide

Imma tech riter, so here are a few random thoughts on tech writing.

• Google helps me on any matters of grammar.
• Sentence case FTW (Say "no" to Pride Capitals; the wiki movement is not a bureaucracy with Test Procedure Specification Reports; and we're not Über Metäl Bands with Germanic Capitalization). en:Wikipedia:Manual of Style/Capital letters#Section headings agrees.
• Avoid passive voice (It has been found that passive voice is to be avoided, but mistakes were made). As you can see, it deadens prose and makes activity description a meandering mess. Instead:
  • Figure out who's doing the work (the user, a function, the extension) and put them in the driver's seat. "A button shows its active state when the cursor is over its active area."
  • Talk to your reader. "You should reduce the number of API requests you make"; "Next, we format the API response" (in a tutorial); etc.

• Ruthless consistency in tech writing is good. Writers get bored writing "* Use the maxlag parameter to specify the delay. * Use the format parameter to specify the API response layout. * Use the action parameter to invoke a particular module.", and so they needlessly mix it up. But readers find it easier and faster to comprehend uniform repetitive structures.
• Use the simplest, older construction. Use not utilize, Affect not impact. But don't be afraid to use le mot juste solely because it's recondite, readers are a few keystrokes away from "define le mot juste" and "define recondite".
• Punctuation avoids ambiguity. I hyphenate three-word phrases (like that one), I favor the serial "Oxford comma" when thanking my parents, Ayn Rand, and God.
• Markup conveys meaning and lets you drop words. "The submitEntry function generates a new Echo email, see the web page API:Email" is just "submitEntry() generates a new Echo email, see API:Email"

etc.