Writing technical docs

This is a guideline for non-teaching technical documentation, for example HPC infra usage. Since many of us overlap with HPC or other support roles and our CodeRefinery mindset partially overlaps, we have some brief guidelines here.

There is far too much professional information for us to reproduce here, but hopefully this is useful quick reference for a typical person to get started. Check the links at the bottom for more.

What kind of doc?

  • Tutorial - emphasis on concepts and mental model, after reading you can do limited things.

  • Reference - more likely to read if you know the concepts and want to know more advanced stuff.

  • Example - example of one specific thing. Good for copying and pasting if you know enough to understand it.

“A good tutorial is different from a good reference. Very few things are good at both at the same time.” - (I don’t remember who, seen in Teaching Tech Together). Thus, both tutorials and reference are useful. Sometimes, we need a tutorial for our stuff and can point to outside material as a reference. People also really want examples they can copy - is your infra similar enough that outside examples can be copied?

Style suggestions

(not standards, since of course people do what they want anyway. Not all things apply in all cases)

  • Bold for definitions or the first time a concept is introduced. Basically, a time where someone is likely to scan up the document to remember what a certain concept is, such as “what’s a git stash?”

  • Italics for local emphasis.

  • Never feel bad to use simpler text, in the best case someone can now understand, in the worst case there’s less mental effort.

  • Use an active/imperative voice (Y does X, do X to get Y), not passive (X can be done by Y). Try to use present tense.

  • Make the docs skimmable - by looking at headings and first words in each section, can you figure out what you need to focus on?

  • Use gender neutral text, of course.

Style guide

(Is it worth making a minimal academic HPC/tech doc style guide? The benefit would be that we can share stuff better. There’s no need to emulate or reproduce actual professional ones, since we probably aren’t that formal.)

Other ideas

Consider documentation-driven development. Write basic docs, review, then implement it.

See also

Of course, there is far more professional information than you can find above.

  • The Write the Docs guide seems useful - especially about organizational aspects.

  • lesson-design.md might be useful to understand. The “backwards lesson design process” is especially important to think about: while you don’t have exercises, you do have goals to accomplish you can design to.