Reimagining documentation
A Hacker Dinners conversation about documentation as a learning practice.
This Hacker Dinners theme asks a simple question: what would documentation look like if we treated it as a learning practice rather than a chore? The conversation is useful for anyone who keeps notes for a circle, a project, or a team.
Why documentation
- Notes let a new member join without starting over.
- Writing something down shows you what you do not yet understand.
- Good documentation is a gift to the next reader.
- A circle that documents its work can outlive its first members.
Prompts for the table
- What is the last piece of documentation that genuinely helped you?
- What do you write for yourself, and what do you write for other people?
- Where does documentation live in your circle?
- What would make you want to write more of it?
Ideas that came up
- Write the short version first, then add detail.
- Keep notes next to the work they describe.
- Treat a question from a beginner as a signal that a page is missing.
- Make the smallest useful note, then improve it later.
Take it back to your circle
Add one page to the wiki after your next meeting. Use the templates so the page fits the rest of the site, and link it from All Pages. For more on the craft, see Write the Docs and Docs for Developers.
Return to Hacker Dinners or read Help.