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

README - example

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

GitHub wiki - example

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

Jekyll site - exampleexpressjs.com

Jekyll site - exampleloopback.io/doc

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 README: Example

Single-sourcing README:Example

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

Summary

Making good docs is a cultural change• Recognize value of docs• Establish processes and framework

Pick the right tool• README only• GH wiki• Jekyll site