Node Interactive North America 2016

Documentation is a weak point for many Node projects. Many developers don’t like writing documentation, and often add it only as an afterthought, or after complaints. But particularly for complex modules or multi-module frameworks, good documentation is essential. For very simple modules, a basic README is often sufficient. But more complex modules or multi-module frameworks need more, and this talk will help developers to understand what is needed for projects of different scopes and how to provide it.  Why is creating and maintaining good documentation so hard? What are the key qualities of good developer documentation? How can open-source projects create and maintain good documentation using free tools such as JSdoc, Jekyll / GitHub Pages? How can you encourage community contributions?

We’ll look at documentation best practices for open-source projects ranging from small and simple to large and complex. We’ll discuss the four basic types of documentation, and when you need each type. We’ll look at Express and LoopBack as example Node.js projects and how they’ve handled issues such as organization, navigation, versioning, and localization (translation). Although the case studies we’ll discuss are Node projects, the basic principles discussed apply to any open-source project.