Documentation

Where to Find Documentation

1. README.md introductory landing page
2. ReadTheDocs user documentation for pyani v0.3.x
3. Wiki documentation for development
4. In the source code for implementation details

Documentation Strategy

We aim to keep documentation in four different places, with a different aim in mind for each.

1. README.md: A user's first encounter with the pyani software and codebase

This should be brief (as short as possible, but no shorter), but provide enough information to the user that they understand

• what the software does
• how to acquire and install the software
  • possibly including requirements (maybe only the key ones, not a list of all dependencies)
  • and maybe also verify that the software is installed correctly
• how to run the software
• where to find more documentation
• where to report a bug, feature request, or other issue
• at least one example use case
• how to cite the software
• who wrote the software
• licensing

2. ReadTheDocs: User-level documentation

This should be extensive and detailed, ideally anticipating user questions

• how to acquire and install the software
• what each command/subcommand/option does
• how to use the software
  • basic use
  • advanced use
  • module import and use
• use cases for solution of specific, named tasks
• how to report bugs, feature requests, or other issues
• a FAQ

3. Wiki documentation: Developer guides, user-level FAQs

This documentation will be dynamic and subject to change as development proceeds; it should not be specific to the repo's contents at any one point in time

• Project roadmap
• How to contribute as a developer
  • project conventions and style (code and documentation)
• Managing issues as a developer
  • how to raise an issue
  • how to handle an issue
  • how to raise a pull request
  • how to handle a pull request
• Testing
  • test style and strategy
  • how continuous integration and testing is implemented
• FAQ: this is intended to be dynamic, with questions moving to the "static" FAQ in ReadTheDocs as they are resolved

4. In-code documentation

• Header/licence information
• File/module-level docstring
• Class/Method/Function docstrings
• Type hints (not compulsory, but useful)
• In-line comments to explain why the code does what it does, or to make relevant notes to help future you/other developers