WPCampus: Documentation for Developers

Developers who love to write documentation are pretty rare. But, documentation is a critically necessary evil throughout a website’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 sails out into the world, without making ourselves completely crazy in the process?

We will explore a structure for documenting your technical requirements and layering them into your codebase, the components of strong documentation and how these project artifacts evolve over time.

**NOTE: You will need to download this deck to click links in the PDF.**

Transcript

1. Documentation for Developers Katherine White WPCampus 2018
2. What we’ll discuss 01 02 03 Why it matters Audiences What to include 04 05 06 Keeping it fresh Making it happen Writing your docs
3. 01 Why it matters The role documentation plays for your projects and for you.
4. You will be using your code
 in a year. Code you wrote six months ago looks like it was crafted by a mad genius. MAINTAINABILITY
5. Someone else will be using your code in a year. Almost 35% of developers cite poor documentation as one of their primary frustrations at work, just behind “unrealistic expectations.” - Stack Overflow Developer Survey, 2016 MAINTAINABILITY
6. You want people to use your solution. Consistency is always a challenge. People don’t use things that aren’t easy to figure out. ADOPTION
7. You want to build a community. To encourage participation, people must grasp the value of the project and how they contribute to it. ADOPTION
8. You want to write stronger, better code. If you want to be sure you understand it, explain it to someone else. PERSONAL GROWTH
9. You want to improve your marketability. Practice makes perfect. The more you write, the easier it becomes. PERSONAL GROWTH
10. 02 Audiences The people who influence your documentation.
11. Stakeholders • May or may not be technical • Understand the business requirements • Care about the organizational impact • Help pay the bills • Drive adoption (or death) of your project
12. Implementers • Have a problem they need to solve • Varying degrees of technical facility • Strapped for time and resources • Need to interact with your functionality but not your code • Can be inside or outside your institution
13. Developers • Adapt and extend your code • Interested in being part of your open source project • Technical teammates • Support the work long-term
14. 03 What to include Writing clear plugin documentation and beyond.
15. For Everyone ✓ What problem are you solving? ✓ How does the thing work? ✓ What are the major features? ✓ How do you install it? ✓ What is it built with? ✓ Where can you get help? ✓ When can you use it? ✓ What has changed between versions?
16. For Developers ✓ How do you set up a local? ✓ How is your project architected? ✓ What are rules of the road? ✓ How is it tested? ✓ How is it deployed?
17. 04 Writing your docs This doesn’t have to be hard. Promise.
18. Your writing matters. • Avoid overly technical jargon • Add links to supporting documentation • Add links to acronyms, technical terms, and third party tools STYLE
19. Think in stories. User stories are a powerful tool for simplifying the explanation of what your code does and why. STYLE As a [user from the user group], I should [description] so that [user-centric reason/strategic benefit/business justification.]
20. Be consistent. Update your documentation regularly as you plan and build your project. It keeps you in the habit and means you don’t have to go back and do it later. STYLE
21. Don’t scope creep. Nobody likes lengthy spec documents. Break your documentation up so it lives at the deepest possible level. STYLE
22. Do what you know. Use a simple text-based format that’s lightweight and flexible. Don’t make this hard. Do what you know. Markdown is pervasive and easy to learn. STRUCTURE
23. Start with a README. A basic overview of your project, theme, or plugin. If you have nothing else, have this. STRUCTURE
24. Have a LICENSE. Provide a LICENSE file that clearly delineates how your code can be used. For WordPress, it should be compatible with GPL v2 or higher. https://choosealicense.com/ STRUCTURE
25. Help others CONTRIBUTE. A CONTRIBUTE file provides a home for information on patching, code review practices, and any other development specific criteria. STRUCTURE
26. Writing Resources • Grammarly: Free Writing Assistant • Readable.io • Hemmingway Editor
 • Markdown Tutorial • Markdown Cheatsheet • StackEdit
27. 05 Keeping it fresh Staying accurate and accessible in your documentation.
28. Have a canonical source. Decentralized documentation hurts. Don’t rely on scattered project artifacts or granular commit messages.
29. Track changes over time. Keeping documentation in your version control system gives a clear picture as code and requirements evolve.
30. Keep it with the code. The code is the only “artifact" that will exist for the full life of your project.
31. Leverage pull requests. Key moments in the code history can provide more granular documentation. Use a template to add structure.
32. Leverage release notes. Change logs don’t just help your users. They help you a year from now.
33. Include project docs. You can use this model, with a 
 /docs/ folder, to support full project documentation that will always live with your site.
34. Generate a static site. Tools like MkDocs and Couscous create HTML documentation sites that get around the limitations of just Markdown.
35. Host the HTML version. Web hosts like Read the Docs, GitHub Pages, and Netlify make it easy and free to create static documentation sites.
36. 06 Making it happen Building documentation into your everyday life.
37. Make it part of the workflow. Consistency is key. Enforce documentation creation as part of your development process.
38. Something is better than nothing. Start small. If it is accurate, and kept up to date, it adds value.
39. The best is the enemy of the good. - Voltaire, La Bégueule ” “
40. Questions? Feedback? ? @katherinemwhite https://2018.wpcampus.org/schedule/documentation-for-developers/