I’m at Write The Docs EU today in Budapest and will post semi–unpolished notes from sessions throughout the day after each talk finishes.
Cake or Death? Variations: Easy option or another easy option?
- Easy to understand.
- Explain common use cases for developers.
Identify scope for improvement.
What helped? If you run into hurdles, document solutions that you find.
Scope of Improvement
- Unified architecture explanation.
- Easy to follow tutorials.
- Explain common use cases.
- Simple sample extensions.
- Look at internal and Google Docs.
- Note down what’s missing, and what works.
- Think of common use cases.
- Make sample extensions for those use cases.
- Document issues he came across.
- Write article explaining API, common use cases, and sample extensions.
- Markdown for tutorials. Much love for Markdown. 🙂
- API docs in plain HTML
- Built with Jekyll
- Available on GitHub
Attribution and Licenses: Creative Commons!
Right type of sample code and sample extension? Make it super simple, almost like a test case.
Sometimes, “the readers are teenagers!” 🙂
Thoughts on feedback. Multiple channels of feedback are good. Most weren’t through technical means, like a GitHub pull request. Also, there were abstract (“pie in the sky”) scenarios.
Ways they can improve their docs:
- Idea: Boilerplate extension generator
- Increase awareness
- Tweak the tone
His key points:
- Have a greater insight on your audience.
- Make sample code and extensions before you write the tutorial.
- Be as simple as possible.
- Have multiple channels for feedback.