Process for creating documentation: some recommendations

[rufuspollock]

Some suggestion on process for creating documentation.

Step by step process

Identify the need

• Nail your job story: make as clear and precise as possible

Notes:

• May be in form of SCQA if you want
• Make it as clear and precise as possible
• Optional: Skeleton the answer (hypothesis tree like if you want!)

Identify what you are creating to address that

• See the 4 types if you haven't already https://documentation.divio.com 👈 really worth a quick read
• Identify type of docs you are doing: tutorial, howto, explanation or reference

Suggestion: Focus on top line to start with i.e. tutorials and howtos) e.g. Start with a tutorial addressing core job story and then ping-ponging with howtos after that i.e. answer howtos a bit and then improve or extend the tutorial.

• Can even ping-pong into reference and explanation
• NB: may also improve your product's UX as you go!

Re writing tutorial

• Skeleton - here's an example for an essay / course in another project https://coggle.it/diagram/ZFInHCHgHRe8lmua/t/diginomics-101-v2-become-a-digital-expert-physical-goods
• Draft text (can include image holders or images if you want - but recommend heavy image work comes later)
• Try it with someone
• Either finalize to a detailed text tutorial with screenshots OR go to video
• Refine

Improvements once finalized

• Screenshots etc (maybe even gifs though at that pont just do a video)
• Turn it into video: you have the script already with the tutorial

Copy and paste-able markdown version for issues

### Identify the need

- [ ] Nail your job story: make as clear and precise as possible

### Identify what you are creating to address that

- [ ] See the 4 types if you haven't already https://documentation.divio.com 👈 really worth a quick read
- [ ] Identify type of docs you are doing: tutorial, howto, explanation or reference
 
 Suggestion: Focus on top line to start with i.e. tutorials and howtos) e.g. Start with a tutorial addressing core job story and then ping-ponging with howtos after that i.e. answer howtos a bit and then improve or extend the tutorial.

- Can even ping-pong into reference and explanation
- NB: may also improve your product's UX as you go!

### Re writing tutorial

- [ ] Skeleton

- [ ] Draft text (can include image holders or images if you want - but recommend heavy image work comes later)
- [ ] Try it with someone
- [ ] Either finalize to a detailed text tutorial with screenshots OR go to video
- [ ] Refine

Improvements once finalized

- [ ] Screenshots etc (maybe even gifs though at that pont just do a video) 
- [ ] Turn it into video: you have the script already with the tutorial