Skip to content
This repository was archived by the owner on Nov 15, 2019. It is now read-only.
This repository was archived by the owner on Nov 15, 2019. It is now read-only.

[doc][improvement] Add README.md in each Measure folder #6

@NG-GOM

Description

@NG-GOM

Documentations of measures are only accessible online, through the Wiki.
It's not at all convenient when working on an isolated environment, where there's no access to "the outside world".

Main advantages I see on using these README files :

  • "Self-documentation" of the module : Having the module's directory is enough to have all the informations needed to understand what is it and how it's used ;
  • "Human-readable" : The Markdown formatting is quite easy to write & read, so even on limited environments (servers accessed through SSH and a basic text tool like vim, cat, less,...) it is easily usable ;
  • Maintenability : README.md are supported by Github, so the wiki could refer to the module's Github directory to display documentation instead of maintaining its own documentation of the module. It would avoid divergences between Wiki documentation and the current state of the module. For example, if a developer forks the project and changes the features of a module, he also can update the documentation accordingly before doing a pull request, thus reducing the work needed to maintain an up-to-date Wiki documentation. Plus, if you have an old revision of a module, you would still have access to its related documentation, as it is versionned with the sources.

It shall contain (non-exhaustive list) :

  • A "Generalities" chapter containing :
    • A (small) introduction to the main project, link to project's website,...
    • A description of the module (a brief sentence + a detailed description)
    • A complete table describing environment requirements (MeasurePlatform version, if relevant : external tools versions,...)
  • A chapter describing the build steps and requirements to generate the module from a reference environment
  • A chapter describing the usage of the module (operationnal configuration, exploitation)

Metadata

Metadata

Labels

No labels
No labels

Type

No type

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions