Skip to content

Instantly share code, notes, and snippets.

@mlapshin
Created October 4, 2018 08:10
Show Gist options
  • Save mlapshin/fdc65bcae617d73449aeebf4c5ef7d41 to your computer and use it in GitHub Desktop.
Save mlapshin/fdc65bcae617d73449aeebf4c5ef7d41 to your computer and use it in GitHub Desktop.
Techwriting Guidlines

Simple rules to follow when you write technical docs.

  1. Explain stupid things. Do not overestimate reader's understanding. Make you instructions and explanations so straightforward and verbose so your mom could follow them;

  2. Do not put periods at the end of headers. "Introduction", not "Introduction.";

  3. Let abbreviations to be abbreviations. They should be all uppercased: JSON, FHIR, API, not json, fhir and api;

  4. Use capitalized form for product names. Aidbox, not aidbox;

  5. Use consistent names for products. Aidbox.Dev, not devbox. Aidbox.Cloud, not "cloud version of Aidbox";

  6. Use consistent naming. Introduce term once and then use same name everywhere;

  7. If there is a command for some product, use lowercase word to name it. Fhirbase is a HS product, and fhirbase is a command name. Git/git, etc.

  8. Use <code> tag for technical stuff: parameter names, table names, API methods, etc. It allows reader to differentiate computer and human terms;

  9. Separate commands and their responses into separate <code> blocks. Do not put them into single <code> block. I watched several times how stupid human copies entire code block and pastes it into terminal. Stupid human does not care what's inside, he just copy and paste.

  10. Use short sentences.

  11. If you're explaining a GUI actions, use screenshots, a lot of them.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment