Posted by s.aragon on 9 November 2018 - 8:27am Image courtesy of Luigi Rosa. ​​​​​​

By Raniere Silva, Software Sustainability Institute.

Documentation is, alongside version control, testing/continuous integration and others, one of the best practices for software development and is crucial for new users. In the recent years, with the professionalism of open source drive by companies such as Red Hat, Anaconda (formerly Continuum Analytics), RStudio, Overleaf, we saw not only releases come out faster but also documentation be richer. If in the early 80s, most of the documentation were available as man pages and books, today users would be able to search in beautiful responsive websites or ask bots for the answers they are looking for. For Collaborations Workshop 2019, we are looking to start discuss documentation from three pillars: project culture, tools and writing style guide.

Project Culture

The very first piece of documentation will probably be written in the README file and will include information on the software itself, installation instructions, common pitfalls, how to get help, etc. On average, README files will be short and point users to more in-depth documentation somewhere else; for example, a static website generated from one version controlled repository, a wiki-like website or a question-and-answers-like website.

Independently from the platform of choice for the project, what do successful projects do to keep contributors motivated in the long run? What safeguards do successful projects put in place to avoid users getting frustrated because the documentation is out of date?

Tools

Popular programming languages, such as Python and R, have a fantastic tool box to help developers write documentation for their packages. For example, Python projects can use Sphinx to "create intelligent and beautiful documentation" that has extensions, among others, to include comments from the source code in a semi-automatic way or insert automatically-generated plots. R is not behind and similar features are provided by the Roxygen package. When the time comes to publish the documentation, many free and paid hosting options are available. For example, Read the Docs can host Sphinx projects for free and GitLab and GitHub can host static websites for free as well. What other great tools do you know?

One thing that a good documentation must have is examples. What if the code examples are interactive? It would be awesome, right? SymPy and spaCy are examples of projects that are using the Cloud to provide interactive code examples that users can run straight from the browser which, as Ines Montani said, "make much easier to try out the function being documented to see how it works." How can we promote this practice to other projects and make interactive code examples sustainables?

Writing Style Guide

A good documentation requires more than a shiny tool box. One pitfall when writing documentation collaboratively is being consistent throughout the document, in other words, using the same structures and conventions that have been used in other parts of the document. Another pitfall is the use of colloquial language and topical expressions, something that should be avoided (though hard to accomplish) when writing to an international audience. Some projects have created great documentation style guides; for example, the Gnome Project, that is an valuable resource for any project. What other resources do you know? What other good writing practices do you follow?

Even having the most consistent documentation, any project can fail because the best search engine will not always get the answers they need since, as Dave Nunez said, "when you're dealing with code names, teams, orgs, people, and other company-specific language, you don't know what you don't know, so how can you search for it?" And the use of the same term to designate something completely different in two projects only make this problem worse. For example, we have the use of the word "window" in Emacs' documentation:

The main area of the frame, below the toolbar (if one exists) and above the echo area, is called the window. Henceforth in this manual, we will use the word “window” in this sense. Graphical display systems commonly use the word “window” with a different meaning; but, as stated above, we refer to those graphical windows as “frames”.

The creation of  five-star documentation requires procedures, culture, data and the most diverse group of people that the project can attract so that users have more than one path to find the answers they are looking for. Some food for thought: how can we collect number of views of documentation and use it to generate paths to help learners?

Image courtesy of Raniere Silva

More at Collaborations Workshop 2019

In addition to the questions raised in the previous sections, we are interested in hosting discussions related to:

• localisation/translation of documentation

• applying accessibility practices to documentation

• chat bots to answer questions with snippets of documentation

Register now for Collaborations Workshop 2019 to take part of the discussion.

If you wish to discuss this post with us, send us an email or contact us on Twitter @SoftwareSaved.