A Documentation Crash Course, LinuxCon 2016
1 like423 views
The document presents a guide on effective documentation for developers, highlighting key questions to consider such as audience, purpose, and clarity. It emphasizes the importance of engaging language, active voice, and concise writing, drawing on notable quotes to stress brevity. Additionally, the document mentions tools for managing formatting, testing, and automating documentation processes.
A Documentation Crash Course, LinuxCon 2016
- 1. A Documentation Crash Course …for developers LinuxCon, Berlin @chrischinch
- 2. What’s one of the first things you look at with a new project?
- 3. • W • W • W ho are you writing for? hat are they trying to achieve? hy are you writing this? Youhavehopefullyansweredthesebeforedevelopment…
- 6. API docs are (not) always enough
- 7. It’s not a manual
- 12. Language Selected highlights in (mostly) English, sorry…
- 14. “function takes parameter x and returns value y”
- 15. “You can use function to return the value of y based on x”
- 17. “function can be used to return the number of y based on x”
- 18. “Holiday approval will be notified in due course”
- 19. Keep it short
- 20. “If I Had More Time, I Would Have Written a Shorter Letter” – Pascal, Locke, Franklin, Thoreau, Cicero, Wilson?
- 21. Structure
- 23. Consistency
- 24. Tools In brief…
- 28. Write your own
- 29. Want More? • www.meetup.com/Write-The-Docs- Berlin • slack.writethedocs.org
- 30. –Me (maybe) “Documentation isn’t just for developers”
- 31. Thank You! Chris Ward contentful.com gregariousmammal.com @chrischinch I have stickers and merchandise!