Documentation for Developers

Developers who love to write docs are pretty rare. But documentation is a critically necessary evil throughout a site’s life, from initial development through to ongoing support and enhancements. How much documentation is too much? Not enough? As developers, how can we produce meaningful documentation that supports our code and sets it up for success once it launches out into the world… without making ourselves completely crazy in the process?

We’ll explore a structure for documenting your codebase, the components of strong documentation, and how these project artifacts evolve over time.

Transcript

1. Documentation for Developers Katherine White
 WordCamp US 2017
2. What we’ll cover • Why write docs • What technology • What to write
3. Why Write Docs
4. Why Write Docs • You (or someone else) will be using your code in six months • You want people to use your code … or to even help out • It makes your code stronger • It builds community • It makes you a better writer
5. What Technology
6. What Technology • Simple is best • Use plain text • Keep it with the code • If it’s version controlled, it’s canonical
7. Markdown
8. Markdown • Widely supported by version control (GitHub, GitLab, BitBucket) • Automagically formats for display • Plain text format • markdowntutorial.com
9. README.md Public repository example: http://bit.ly/2zcfgkx Private repository example: http://bit.ly/2hadc8h
10. CONTRIBUTING.md Creation guide: http://bit.ly/2zhQ5iC
11. What to write
12. What to Write • What problem does it solve? • What are the major features? • How do you install it? • Code examples and tutorials • How to reach a human for help • Links to code and issues • Changelog • Licensing information -
 https://choosealicense.com/
13. What to Write • Public and private repos need different care and feeding • Consider your audience • Keep it up to date • If you’re inviting contributions, tell people what to expect
14. Conclusion • Why write docs • What technology • What to write
15. Questions & Feedback • Here and now • katherine@kanopistudios.com • @katherinemwhite