Open-Source Software DocumentationBest Practices

OW2 Technology CouncilOscar Quality Programme

oscar.ow2.org

Foreword

2

Preliminary Remarks

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

Source: 10 tips for better documentationPaul Adams, director of engineering at KDAB

3

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.

Examples of Outstanding Project Documentations

Nuxeo doc.nuxeo.comOpenStack docs.openstack.orgEclipse help.eclipse.orgDocker docs.docker.comOW2 projects:

Proactive Workflows & Scheduling BonitaWebLabHammrCollab projects: XLCloud / Choreos

4

Key Recommended Features

Attractive home page with nice layout

Common formatting across sections

Outline for easy navigation

Syntax highlighting

Screenshots

Search

Glossary

Accessibility

5

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

6

DocumentationTypes

7

Documentation Types

1. Getting started2. Installation and administration guide3. User guide4. Developer guide5. API documentation6. Code documentation7. Tutorials / cookbooks / recipes

8

1/7 Getting Started or README Documentation

It is the strict minimumMust have sections:

Project’s featuresRequirements and installationSupportLicense

9

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

Example: erocci

2/7 Installation and Administration Guide

Purpose: provide guidance on the software installation and on its configurationRecommended sections:

RequirementsInstallation stepsSystem configurationSystem monitoringPerformance tuning Troubleshooting

10

Example: XWiki

3/7 User Guide

Purpose: present the software goals and usage in greater detailsRecommended sections:

Table of content

One section per main function

Screenshots

FAQ

Links towards further help

11

Example: Lutece

4/7 Developer GuidePurpose: facilitate developer contributionRecommended sections:

Getting the code

Build instructions

Architecture with diagrams

Issue tracking + easy bugs

Coding conventions

Patch submission

Testing process

Translation process12

Example: WebLab developer guide

5/7 API Documentation

REST APIs: list all end points

Provide sample code

Consider API description languages: Swagger, Raml, JSON Hypermedia

Use an efficient UX

13

Example: ProActive Workflows & Scheduling

6/7 Code Documentation

14

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

7/7 Tutorials, Cookbook, Recipes

15

Purpose: help solve specific problems and reduce the learning curveBest practices:

Use several formats to address different learning profiles: code recipes, videos, slides, …

Promote community materialExample: SpagoBI

Tutorials

Toolsand

Resources

16

Enterprise scriptable wikiLGPL v2, Java10+ years project and companyXWiki SAS OW2 corporate memberKey features for documentation:

Collaborative editingContent versioningSyntax formattingTable of contentDocument inclusion supportUML diagramming extensionsInternationalizationPDF export

Recommended Solution for Writing Documentation: XWiki

17

XWiki.org

Tools for API documentation, diagrams, a11y, …

REST API documentation generation: Swagger, MiredotDoc and UML diagrams generation:

Doxygen

Forums: discourse.orgAccessibility check: AsqatasunIssue tracker for keeping track of documentation related issuesAlternative writing tools: Corilla, Sphinx

18

Collaborative Project Documentation How-To

Create a dedicated space in the project’s public wikiRequest the creation of a dedicated navigation panelYour contacts at OW2:

Olivier Bouzereau, community coordinator

Olivier Lizounat, webmasterStéphane Laurière, CTOReach OW2 also via your project’s JIRA

19

ResourcesArticles and guides

Doc-dish articles on opensource.com

Oscar wiki – Documentation section

Publication / Dissemination

FLOSS Manuals.net

Community events

Write the Docs

Open Help

20

ContributorsList here who contributed to the guide +

tell about the license

21

Open-source Software DocumentationBest Practices

Thank youoscar.ow2.org

22