Modern technical writing - Andrew Etter 2016

Style
Basics

I hate the overbearing nature and rigidity of comprehensive style guides, but I'd be remiss if I didn't at least mention style. Don't worry, I'll keep it quick:

· Consistency is king. You sound unreliable if you use "Postgres" at the beginning of a sentence, "postgres" in the middle of a sentence, and "PostgreSQL" in one or two random locations. Abbreviations are fine, but use them consistently, ideally after introducing them:

PostgreSQL (Postgres) is a popular open-source database.

Likewise, if you call something a dialog in one document, don't call it a pop-up in another.

· Bias towards including headers, tables, lists, diagrams, and images. These additions make your writing more approachable and simpler to scan than paragraph after paragraph of prose. For example, almost all descriptions of how to do something should include an ordered list. In my coffee example, would an unordered list (or a table) have improved the second paragraph?

· Use inline styles to offset important text. Typically, technical writers use bold for user interface elements ("Click Save."); italics for emphasis ("You must save your work before shutting down."); and monospace for file paths, terminal commands, and code ("Run ./bin/script.sh.").

· For the sake of clarity, try not to verbify obscure nouns. An extreme example: "Grep it." vs. "You can use grep to search the file."

· Copy edit, but don't obsess over it. A stray comma or dangling preposition isn't the end of your credibility. You can probably find a typo in this book. More than one, actually.