User:SPage (WMF)/On tech writing

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 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 "  generates a new Echo email, see API:Email"

etc.