PDS Software Documentation Best Practices¶

The following page will outline some best practices for PDS Software Documentation.

Purpose¶

To develop a set of best practices and guidelines for developing and generating software documentation to ensure consistency across software repositories.

Requirements¶

General Requirements¶

PDS shall only host online the latest version of software documentation.¶

Ensures we don’t bump into changing versions breaking links or people downloading the wrong version. Also eliminates the possibility that Google will index and link to older versions of the docs / software.

PDS shall host software documentation on Github Pages for all Open Source repositories¶

We should use Github Pages as much as possible to minimize confusion. We may even want to look at

PDS shall generate a documentation package with each release and upload to Github Release Assets.¶

This ensures we have links to past documentation that can be downloaded and used, but this is not hosted online.

PDS shall generate a Past Releases page for each software tool, which includes links to the source code / download package and documentation.¶

For Python applications, this should link to source code download links. For Java applications, should link to the download applications. For other programming languages, default to linking to source code.

PDS shall include, at minimum, the following documentation pages: Installation, Usage (or Operation), Developer, Support.¶

Best Practices and Guidelines¶

Installation Documentation¶

TBD template?

Usage Documentation¶

TBD template?

Developer Documentation¶

Should include, at minimum, the following information (should this just link to the repo README?):

Build from source instructions
Release instructions
Contribute information

Support¶

Should look something like the following:

Found a bug? Or want a new feature? We would love your feedback and contributions. Please submit new issues into our repository Github Issue Tracking:

Issue Tracking: https://github.com/NASA-PDS/pds-deep-archive/issues

If you require additional help or more immediate assistance, please email us at pds-operator@jpl.nasa.gov