Documentation


Home

Documentation

« Back to Policies and Guidelines home


Legend

generic badge Designates a mandatory point (policy).

generic badge Designates a recommended point (guideline).


Generic badge Develop documentation from a readable plain-text format that can be publish documentation in a web-based format or as a PDF

Rationale
Web-based documentation is accessible, searchable, and linkable. It allows users to easily point each other to relevant parts of the documentation in emails, the code, and other documents. It also makes it easier to manage under revision control (see also M.doc.3). All of these tools allow developers to create web-based manuals and API documentation automatically, using a familiar, non-HTML plain-text format. Examples:
Ref
WSC 4.1
WSC 4.4

Generic badge Provide a concise description of the software functionality wherever your project is summarized

Details
The description should typically be answering “What is it for ?” and “Should I use it ?”, and not simply an extension of an acronym or otherwise fully generic description that does not differentiate the software from other products. This description (1-3 sentences) should be consistently used in:
  • The GitHub host web interface (modified with the ‘Edit’ button)
  • The top of the root README.md
  • The corresponding Spack package
Rationale
Developers who come across your project or repository should be able to determine almost immediately if your project is applicable to their needs. The GitHub repo description is also used as the basis to automatically describe each project at https://software.llnl.gov/.

Generic badge Version control your documentation consistent with and alongside your source code.

Rationale
When documentation is version controlled consistent with the corresponding source code, developers and users can easily retrieve the documentation associated with any revision of the code. Versioning documentation along with source code (in the same repository) also allows and encourages any developer to easily contribute to the documentation as part of their pull request.
Ref
WSC 4.3

Generic badge Provide a documented, reliable way to contact the development team.

Details
Contact can be through email address, a web-based submission form, or via GitHub (issues, pull requests). In the case of email, a generic name is preferred that can be reflected to alternate or multiple team members as needed. Joining a mailing list should not be required.
Rationale
Users should be able to easily contact the development team in order to report bugs or request basic assistance. RADIUSS can provide support for those libraries included in the RADIUSS project for basic fixes and support.
Ref
xSDK M5

Generic badge Provide and maintain example source code along with documentation.

Details
Examples should be compiled and tested as part of a release to make sure they are kept up to date with API changes. New examples should be added when major new features are released, or existing examples should be extended to include those new features. Existing proxy apps are a potential good starting place.
Rationale
This recommendation serves two purposes. The first is for documentation of the concrete usage of the product, training, or new feature demonstration. The second is for maintenance purpose as these examples provides a primary set of tests for non-regression or installation verification (see Testing and Continuous Integration).

Generic badge Provide a documented policy for handling pull requests from external contributors

Details
Successful open source projects will attract bug fixes and feature development from the external community, preferably via pull requests on GitHub associated with a particular issue in the tracker. Teams should have a policy documenting expectations for when a pull request may be accepted, rejected, or returned for modifications.
Rationale
Developers providing fixes will be discouraged from future contributions if they feel they are being ignored. Similarly, they are probably using a branched version of your software to workaround the fix they provided, which leads to additional inefficiencies.