The One Good Tutorial software documentation checklist is a matrix. We suggest that you work through each phase top-to-bottom, before moving from one phase to the next (left to right). But there’s no reason you can’t skip around!
| Plan | Draft | Assess | Revise | |
|---|---|---|---|---|
| 🗺️ Synopsis |
☐ |
☐ |
☐ |
☐ |
| 🧑 Personas |
☐ |
☐ |
☐ |
☐ |
| 🗒️ Tutorial |
☐ |
☐ |
☐ |
☐ |
| 🗒️ Install Instructions |
☐ |
☐ |
☐ |
☐ |
| 🗒️ Citation Instructions |
☐ |
☐ |
☐ |
☐ |
| ⚖️ License |
☐ |
☐ |
☐ |
☐ |
| 🗒️ How to Contribute |
☐ |
☐ |
☐ |
☐ |
| 🖥️ API Reference |
☐ |
☐ |
☐ |
☐ |
| 📚 Other Reference |
☐ |
☐ |
☐ |
☐ |
| 🗒️ Acknowledgments |
☐ |
☐ |
☐ |
☐ |
| 🛠️ Authoring Tools | ||||
| 🚀 Release Process |
☐ |
☐ |
☐ |
☐ |
Summary: Jot down 1–3 draft sentences summarizing your software.
Why: Your final synopsis will end up everywhere: at the top of your README or website, in announcements, maybe even grant proposals. Best to get a rough draft ASAP!
Summary: Imagine 1–3 “personas” of people who might be reading your documentation.
Why: As you’re thinking about the different documents you’ll need to write, it can be helpful to keep these user archetypes in mind. “Hmm, Postdoc Pete is in too much of a hurry to follow this 20-step recipe!”
Summary: Plan out a tutorial that will show new users how to accomplish something cool using your software.
Why: People learn by doing. If someone has read your synopsis and is still interested in your software, they’re not going to want to read pages of additional text about it — they’re going to want to run your code ASAP and learn what it “feels like”. The goal of your one good tutorial is deliver this experience as painlessly as possible. Your tutorial is your software’s make-or-break moment — so invest in it accordingly!
plan-installation.
plan-citation.
plan-license.
plan-contributing.
plan-api-ref.
plan-other-ref.
plan-acknowledgments.
plan-release-process.
plan-synopsis.
plan-personas.
draft-tutorial.
draft-installation.
draft-citation.
draft-license.
draft-contributing.
draft-api-ref.
draft-other-ref.
draft-acknowledgments.
draft-release-process.
assess-synopsis.
assess-personas.
assess-tutorial.
assess-installation.
assess-citation.
assess-license.
assess-contributing.
assess-api-ref.
assess-other-ref.
assess-acknowledgments.
assess-release-process.
revise-synopsis.
revise-personas.
revise-tutorial.
revise-installation.
revise-citation.
revise-license.
revise-contributing.
revise-api-ref.
revise-other-ref.
revise-acknowledgments.
revise-release-process.