Software documentation

[j-i-l]

See the relevant section in the JOSS review criteria.

The following elements are required in an adequate documentation:

• README.md providing at least
  • [ ] high level overview
  • [ ] links to all other items of the documentation)
• A statement of need to clarify
  • [ ] What problems this software is designed to solve
  • [ ] Who is the target audience
  • [ ] Mention related other work
• Installation instructions
  • [ ] handled by package manager
  • [ ] explicitly state dependencies (plus how to install them)
• Example usage
  • [ ] #15
  • [ ] #16
• API documentation of all exposed functions
  • [ ] Minimal description of the purpose
  • [ ] Declare input and outputs
  • [ ] Provide basic application example
• Community guidelines
  • [ ] How to proceed in order to contribute to this software
  • [ ] How to report issues, problems and suggestions
  • [ ] Where/How to seek for support

We need to decide how we want to structure this documentation, i.e. what should reside directly in the README.md, what in some online documentation and what parts should reside just within the repository.