Documentation

Upload a README file to the main repository

  • Day1

  • Plugin

  • NewProduct

  • Publication

This must include the declaration of intent and the other information mentioned throughout this Guide that has to be included in the README file.

It must be written in English and the format has to be text with light markup language. It cannot have an extension if it is written in plain text, or it can have an extension that indicates in what format the markup has to be interpreted (i.e. in reality the file will be called README.md if it is written in Markdown).

The content of this file (more specifically the version posted in the master branch), formatted according to the conventions of the markup language used, is what GitHub Gitlab and similar software shows as the development website’s home page. So it is important to check the format is correct and that it appears correctly in a browser.

Use wiki formats or free markup formats for all product documentation

  • Integration

  • Plugin

  • NewProduct

  • Publication

For the project user website it is acceptable to write directly in HTML. Other documentation, whether or not it is included in the repository code, will be in the corresponding wiki format or in one of the following formats:

  • Asciidoc

  • Markdown

  • ReStructuredText (the Sphinx default format)

  • Org Mode

Document the project so third parties can understand it, configure it and download it

  • Procurement

  • Integration

  • Adaptation

  • Plugin

  • NewProduct

Organisations awarded contracts — development and deployment — have to understand they will not have a monopoly over the configuration, deployment and maintenance of the product.

Create and maintain a User Guide in the project’s GitHub/Gitlab wiki

  • Integration

  • Plugin

  • NewProduct

  • Publication

From a very early stage there has to be accessible documentation via web that explains how to use the product on different levels or for different roles: average users, administrators, etc. In the case of code libraries, the users are code programmers who do not participate in the project.

A careful assessment needs to be made regarding which languages this documentation should be written in, depending on the sphere the product is expected to be used in. Catalan or Spanish could be the main language but at least the main administration tasks should also be explained in English. If interest is shown from other countries, it would be worth translating all the user material into English as well. All code library and development tool documentation must be in English from the start.

The documentation will never be complete and will be constantly evolving. So it should be easily updatable by different people and we recommend initially using a wiki. Using the same GitHub wiki avoids us having to create more infrastructure and means the documentation is automatically linked from the repository webpage.

Until there is a lot of user documentation, it is advisable to keep it all together in one wiki page, with a table of contents at the beginning, and not subdivide it into pages, as this makes it easier to search for key words by using the browser search features. This page should be linked with other documents such as the installation instructions, any tutorials or the optional FAQ list.

Include or link from the:

  • Project website.

  • The README file of the main repository.

Create and maintain a User Guide in Sphinx and publish it in the GitHub Pages

  • Plugin

  • NewProduct

This is an alternative for projects that grow a lot and might have started by putting documents in the wiki. Any documentation found in the wiki must be transferred to the new format and the wiki itself deleted, so as not to confuse users. If it is clear from the outset that the project will need a large amount of documentation, we can opt to go down this road from the beginning.

All the documentation will go in a doc subdirectory in the repository’s root directory and either be written in ReStructuredText or Markdown, the two markup languages supported by Sphinx.

In this case, given the projects are big and have to aim to attract broad audiences, the documentation will have to be in English, notwithstanding the fact they could be translated into other languages.

Having the code and documentation in a single repository, far from being a problem, facilitates both being synchronised and this being reflected in the commit log.

Link from the:

  • Project website.

  • The README file of the main repository.

You can find an example at: https://github.com/commercialhaskell/stack/tree/master/doc

Recommendation: Create and maintain a FAQ list R_4B1

tags: NewProduct Publication
links incoming: None
links outgoing: None
If this is done reactively but diligently, with real user questions, it can make it much easier for people to find the information they need and could prove to be a very profitable way of investing the project’s resources.

Create a tutorial explaining how to do some of the usual tasks, step by step

  • Plugin

  • NewProduct

  • Publication

Upload a file with installation instructions to the main repository

  • Day1

  • Integration

  • Plugin

  • NewProduct

  • Publication

The installation procedure developed in the Measure: (Day 1) Implement build and installation procedures with free, widely used tools has to be explained in an INSTALL file in the root directory of the main repository.

It must be written in English and the format must be text with light markup language.

Some diagnostic measure or command should be included to let users know if the product has been properly installed (e.g. by performing a set of tests, and specifying the expected result).

The installation file must at least be linked from:

  • The README file of the main repository.

Supplement the user documentation with screen captures, videos and demo sites

  • NewProduct

For big projects that aim to attract the attention of lots of people, the big appeal is a demo site.

A video explaining the tool’s use and characteristics might also be very attractive.

If the product has a graphic user interface, it is highly recommended that the explanations be accompanied by screen captures. They could also be used in the features list described in the #h:2dc43f4e-e755-4fe5-be4e-1f9dd58fe9e9[Measure: Specify a feature list in easily accessible locations].

Specify, in a prominent location, a distribution licence for the User Guide

  • Integration

  • Plugin

  • NewProduct

  • Publication

The default licence to use is Creative Commons Zero v1.0 Universal (CC0-1.0).

A summary of its characteristics can be found at: https://tldrlegal.com/license/creative-commons-cc0-1.0-universal.

There is no reason to use the same licence for the documentation as for the software itself. In fact, Public Domain licences are admissible in this case.

When creating documentation for external projects, use the licences those projects are already using.

Specify, in a prominent location, a distribution licence for the design documents and studies commissioned

  • Document

The default licence to use is Creative Commons Attribution Share Alike 4.0 (CC-BY-SA-4.0).

Follow: https://wiki.creativecommons.org/wiki/Website/Publish and https://creativecommons.org/choose/#metadata.

To understand its characteristics you can consult: https://tldrlegal.com/license/creative-commons-attribution-sharealike-4.0-international-(cc-by-sa-4.0).[https://tldrlegal.com/license/creative-commons-attribution-sharealike-4.0-international-(cc-by-sa-4.0)].