Documentation Journey

A talk about Documentation I gave a PDXNode in November 2013

Transcript

1. Eric Holscher PDX Node Nov ‘13 Documentation Journey
2. What This Talk Is • High level overview of how to think about documentation • Why documentation matters • Overview of my thoughts on doing docs well • Discussion around Node community documentation
3. What this talk isn’t • Telling you how to write docs • User/Product documentation
4. Disclaimer • I don’t know a lot about Node
5. Who am I • Maintainer of Read the Docs • Co-Organizer of Write the Docs
6. Why Write Docs
7. You will be using your code in 6 months
8. You want people to use your code
9. You want people to help out
10. It makes your code better
11. You want a (better) community
12. You want to be a better writer
13. Documentation as Empathy
14. outreach • We want more people to code • How do I become a programmer? • Having good documentation allows people to learn how to program
15. Internationalization • Documentation is much more accessible for non-native speakers • Text is most easily translated into other languages
16. Other Audiences • Each tool is unique • People want to use your code, so make it easy for them, whoever they are.
17. Good Documentation
18. Types of Documentation • Tutorials • Overviews and Topical Guides • Reference Material
19. Tutorials • Be quick • Be easy (but not too easy) • Give a “feel” for your project
20. Tutorials • Great for people who are new to your project • Should aim to delight or scare
21. Topical Guides • High level concepts • Vertical component • Comprehensive
22. Topical Guides • Great for people who don’t know your project space well • Give you the “why” • The “meat” of your docs
23. Reference • Provide lists of classes and modules • Organize by hand, generate to keep up to date
24. Reference • Great for users who already use your so ware • Give you the “how”
25. Official • Good documentation comes from the project • Must be constantly updated with code changes • Put process in place
26. If you only have reference docs, your docs are broken
27. Current Tools
28. README’s • Great for small projects • Provide a very specific thing • Basically a “getting started” doc
29. Blog Posts • Quickly goes out of date • Stack Overflow solves this problem better • Good for Topical Guides
30. Wiki’s • No ownership • Lower quality based on “someone will fix it later”
31. Books • Free projects should have free documentation • Books are effectively always out of date
32. Reference • Generally provided by automated tools • http://jsdoc.info/
33. State of the Art • Folder Full of Markdown • Served on GitHub • “Website”
34. Missing bits
35. Missing Bits • Overview of ecosystem/project • Central Repository for Prose Documentation • Standard Tools
36. Standard Tooling • Need a common format • Where you go a er a folder full of markdown • Not “build a custom website”
37. Documentation Focused • Not a website builder • Needs primitives specific to documentation
38. Tooling Benefits • Search • Discovery • Design • Interoperability • Platform (API)
39. Easy and Obvious • New users need an easy way to get started • There needs to be an obvious path towards a good solution
40. Path Forward
41. Community • Docs are a community problem • You need to expect them and complain if they don’t exist
42. Young • You can help shape what the world looks like • Derived projects will follow your lead
43. Conclusion • Good documentation is hard work • Documentation acts as outreach • Work to improve tools, to make writing documentation easier
44. Reference Links • jacobian.org/writing/great- documentation/ • docs.writethedocs.org/en/latest/ writing/beginners-guide-to-docs/
45. Thanks • @ericholscher • eric@ericholscher.com • Questions?