Open-Source Software Documentation Best Practices

This page gathers resources and best practices on the topic of open-source software documentation. It's a collective work by the OW2 Technology Council. It is available both as HTML (below) and as a presentation.

cover-page.jpg
Open-Source Software Documentation Best Practices v0.1

Table of content:

Introduction

Foreword

geek-and-poke-documentation-is-key.jpg

geek-and-poke-i-read-the-whole-documentation.jpg

Preliminary Remarks

Reading the documentation is how users and developers will get one of their first impressions about your project. They will infer much about the project’s quality itself from their experience with the documentation.

“Documentation can't be an afterthought – it needs to be part of the release process.”

Source: 10 tips for better documentation – Paul Adams, director of engineering at KDAB

Examples of Outstanding Project Documentations

Key Recommended Features

  • Attractive home page with nice layout
  • Common formatting across sections
  • Outline for easy navigation
  • Syntax highlighting
  • Screenshots
  • Search
  • Glossary
  • Accessibility

NB:

  • A glossary will avoid misunderstandings and users will appreciate improving their knowledge of general concepts
  • Dedicated sites become the standard

Before Writing…

Before writing, ask yourself:

“Why do my readers need this content? This question is probably the trickiest of all, because it puts the purpose of your content under scrutiny with the WIIFM (what's in it for me) test: Why are you even writing this content? Which pain are you solving for your readers? Why would they care about what you're writing? Lots of hard questions to answer, I know.”

Source: Content strategy: the new philosophy of technical documentation – Mikey Ariel, RedHat

Documentation Types

  • Getting started
  • Installation and administration guide
  • User guide
  • Developer guide
  • API documentation
  • Code documentation
  • Tutorials / cookbooks / recipes

Note: see also Integration guide

Getting Started or README Documentation

  • It is the strict minimum
  • Must have sections:
    • Project’s features
    • Requirements and installation
    • Support
    • License
  • A short description of the team who's behind the project is important for community building. It will help the reader and potential user or contributor to engage the conversation.

NB: “All this has to be written for someone who never heard of your project before, and may never even have considered something like your project. If you’ve got a module that calculates Levenshtein distance, don’t assume that everyone reading your README knows what that is. Explain that the Levenshtein distance is used to compare differences between strings, and link to more detailed explanation for someone who wants to explore its uses” Source: 13 Things people hate about your open-source software docs

Installation and Administration Guide

  • Purpose: provide guidance on the software installation and on its configuration
  • Recommended sections:
    • Requirements
    • Installation steps
    • System configuration
    • System monitoring
    • Performance tuning
    • Troubleshooting

User Guide

  • Purpose: present the software goals and usage in greater details
  • Recommended sections:
    • Table of content
    • One section per main function
    • Screenshots
    • FAQ
    • Links towards further help

NB: some screen captures can be automated during the testing process to be kept up to date.

References:

  • Snort FAQ: it includes a handy aggregation of links to all the READMEs

Developer Guide

  • Purpose: facilitate developer contribution
  • Recommended sections:
    • Getting the code
    • Build instructions
    • Architecture with diagrams
    • Issue tracking + easy  bugs
    • Coding conventions
    • Patch submission
    • Testing process
    • Translation process

API Documentation

  • REST APIs: list all end points
  • Provide code snippets
  • Make the code snippets searchable
  • Consider API description languages: Swagger, Raml, JSON Hypermedia
  • Use an efficient UX

Code Documentation

  • Code artefact naming is documentation
  • Use consistent naming rules
  • Documentation tells what you are doing, code shows how you are doing it and comments explain why you are doing it this way
  • Reference issues

Tutorials, Cookbook, Recipes

  • Purpose: help solve specific problems and reduce the learning curve
  • Best practices:
    • Use several formats to address different learning profiles: code recipes, videos, slides, …
    • Promote community material

Tools and Resources

XWiki

  • Enterprise scriptable wiki
  • LGPL v2, Java
  • 10+ years project and company
  • XWiki SAS OW2 corporate member
  • Key features for documentation:
    • Collaborative editing
    • Content versioning
    • Syntax formatting
    • Table of content
    • Document inclusion support
    • UML diagramming extensions
    • Internationalization
    • PDF export

NB: Some projects set up a Continuous integration and delivery for documentation (e.g. OpenStack)

Tools for API documentation, diagrams, a11y, …

Publication tools

This section covers tools helping publish documentation in various formats

  • Booktype
  • to be completed

Resources

Articles

Books

  • to be completed

Videos

  • to be completed / short introduction videos / lectures

Publication / Dissemination

Open Source Software

  • Corilla - "Collaboration and publishing tools for technical writers"
  • XWiki

Events

Comics

(please consider adding the comics as an attachment to this page if the license permits, to make sure we have access to a copy)

Contributors

  • Olivier Bouzereau - OW2
  • Daniele Gagliardi - Engineering
  • Stéphane Laurière - OW2
  • Cedric Thomas - OW2

License

This content is available under the Creative Commons Attributions Share Alike v3 License.


Tags:
Created by Stéphane Laurière on 2016/06/24 10:20
6.4.4