-
Notifications
You must be signed in to change notification settings - Fork 3
Software Docs Guide
The following page will outline some best practices for PDS Software Documentation.
To develop a set of best practices and guidelines for developing and generating software documentation to ensure consistency across software repositories.
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.
TBD template?
TBD template?
Should include, at minimum, the following information (should this just link to the repo README?):
- Build from source instructions
- Release instructions
- Contribute information
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 [email protected]
Copyright © 2021-2024 California Institute of Technology.
Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.