SW Documentation
================

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

..  toctree::
    :maxdepth: 3

    /developer/sw_doc

--------------

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 in all repos:

::

   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