Beyond the README:Creating effective documentation
for your project
C. Rand McKinney, IBM/StrongLoop
Why is documentationimportant?
Module users / consumers • Code more efficiently • Use features to their fullest
Module owners / producers • Promotes adoption, participation • Reduce support burden (answering questions)
Good documentation:Especially important for Node
• Power comes from module ecosystem
• “Peer-to-peer” ecosystem • Devs are both module consumers and producers
• Open source!
Know your audience
• Contributors• Internals are usually relevant• Testing info• Process guidelines: issues, commits, PRs, etc.• Coding style guide, etc.
• Users • Internals usually not relevant• “Just tell me how to use it!”
Why are docs often so bad?
• Functionality comes first!aka Lack of resources
• Developer culture - doesn’t recognize value of doc
• “Doc rot” - lack of maintenance
• Creating and maintaining good docs is “just hard…”
Why is writing good doc so hard?
• Requires disparate skills• Writing• Coding (at least code literacy)
• Requires discipline
• You have to walk a mile in users’ shoes
• Developer machismo
The code is the documentation!
Good documentation:WHAT
Describes:
• What the module does and why (Overview)
• How to get started
• Basic use cases
• Examples and best practices
Good documentation:WHAT
• Accurate, complete, and concise• Easy to use for everyone• Well-organized• Up-to-date
Easier said than done!
Good documentation:HOW
• Accurate, complete, and concise → Make it easy to write / contribute → Provide reusable authoring elements
• Easy to use for “everyone” → Good layout, design, and usability → Globalization, accessibility → Responsive design
Good documentation: HOW
• Well-organized → Good navigation → Accurate, usable search → Cross-references
• Up-to-date → Make it easy to write / contribute → Maintenance process: “Does this code change affect doc?”
Good documentation: HOW
Developer culture• Require docs and tests for all PRs (as relevant)
• Create a good (appropriate) doc framework
• Encourage doc contributions
Basic types of documentation
1. (API) Reference - Foundation2. Task - Framing3. Concepts - Wiring & Plumbing 4. Tutorial - “Finishes”
Written in opposite order in which they’re typically read
Creating docs is like building a house
API Reference documentation:The foundation
Auto-generated• Source-code comments• JSDoc, Docco, Doxx,
YUIDoc, et. al.
Hand-written** Best for small APIs
Task and concept documentation:The framing
Tasks• “How Tos”• Recipes
Concepts• Ideas you need to know• Can provide in high level intro• Not all projects need them
Tutorials:The finishing touches
• Walk throughexamples / use-cases
• “Getting started” / Quick start
• Most time-consuming to write
Good examples are critical
• People learn best from examples
• “Cut-and-paste” programming
• Starting point templates
• Use in reference, tasks, tutorials
Options for docs on GitHub
1. README - necessary but not always sufficient 2. GitHub wiki3. GitHub pages site - Jekyll
Jekyll:• Static site generator• Author in markdown • Liquid template engine
README
Pros:• First stop• Auto-publish to npm
Cons:• Limited to markdown• Awkward if too long• No custom display
Every repo needs a decent README, even if it has other docs.
README guidelines
• Summary / overview• Installation
npm install xxx• Basic use / example• API documentation
• Related resources• Link to contributor info• Tests• Link to license
Maybe: Badge board, list of maintainers, etc.Details: http://loopback.io/doc/en/contrib/README-guidelines.html
GitHub wiki
Pros:• No setup• Custom or auto-navigation• Easy authoring & updating
Cons:• No custom display• Poor discoverability• No custom domain
• Doesn’t clutter repo with doc commits
GitHub wiki
• OK for medium-sized projects
• Good intermediate step from README → Jekyll
• Ideal for internal projects
Jekyll site
Pros:• Customizable layout, navigation, branding, etc.• Extensive functionality• “GH Pages” auto-publish • Publish to github.io or custom domain
Cons:• Complexity (not really!)• Hard to combine doc from multiple repos
What about multi-module frameworks?
• Use READMEs for individual repos
• And in broader context of framework docs
• Single-sourcing FTW!
Single-sourcing READMEs
npmnpmjs.com/package/repo
Jekyll-based doc sitee.g.loopback.io/...expressjs.com/...
GitHub READMEgithub.com/org/repo
Single-sourcing READMEs - How?
• Copy manually (not recommended)
• Bash script (e.g. Express)
• Node script:https://github.com/strongloop/get-readmes
• Jekyll pipeline & bash script (e.g. LoopBack)
Best practices
• Single source!
• Encourage community contributions
• Manage doc tasks with labels:• “Needs doc” - code changes that require doc work• “Doc” - actual doc task