CMA1: Documentation

The NASA RRL scale looks at the overall document suite, but it is both pragmatic and useful to break that down into three: end-user, operational and development documents. End-user documentation is considered to be part of the service-wrap and is therefore excluded from this product-oriented collection.

• Minimum standard - SML2

• Expected standard - SML3

• Excellent standard - SML5

CMA1.1: End-user Documentation

SML1 - Initial usability: Partial or no external documentation available; Documentation is insufficient to gain an understanding of the functionality of the software even for an experienced user.

SML2 - Use is feasible: There is external documentation that is accessible and sufficient for an expert user to configure and use the software for the user’s individual needs. Terminology and methodology is not explained.

SML3 - Use is possible by most users: There is a user manual that can guide a reasonably skilled user through use and customisation of the software to the user’s individual requirements. Terminology and methodology is well explained. Documentation is consistent with the current version of the software.

SML4 - Software is usable: There are examples of walk-through tutorials, how-to guides and demonstrations of various use case customisations if applicable for the user’s individual needs. Documentation is consistent with the current version of the software.

SML5 - Demonstrable usability: User materials and tutorials can be used as training resources. There is detailed in-software contextual user support documentation. Documentation is consistent with current version of the software. User created documentation and comments form part of the documentation available.

CMA1.2: Operational Documentation

SML1 - Initial usability: Partial or no external documentation available; Documentation is insufficient to gain an understanding for the deployment and configuration of the software without additional technical support or significant investment of time.

SML2 - Use is feasible: There is external documentation that is accessible and sufficient for an expert to deploy and configure the software for all users. Terminology and methodology is not fully explained. Exception and failure messages are not fully explained.

SML3 - Use is possible by most users: There is a deployment and configuration manual that can guide an experienced operational user through deployment, management and configuration of the software. Exception and failure messages are explained, but descriptions of solutions are not available. Terminology and methodology is fully explained. Documentation is consistent with current version of the software.

SML4 - Software is usable: There are examples of walk-through tutorials and demonstrations of various configurations if applicable. Exception and failure messages are fully explained, and solutions are documented. Upgrade workflows are fully documented. Documentation is consistent with the current version of the software.

SML5 - Demonstrable usability: Documentation is appropriate for different categories of deployment and management of the software. Deployment and configuration demonstrations, materials and tutorials can be used to teach other users. Documentation is consistent with current version of the software. User created documentation and comments form part of the documentation available.

CMA1.3: Development Documentation

SML1 - Initial usability: Partial or no external documentation is available for the application programming interface (API). If available, the source code is partially or inconsistently commented. Documentation is insufficient to gain an understanding of the software functionality without a significant investment of time.

SML2 - Use is feasible: There is external documentation that describes public API functionality and is sufficient to be used by an experienced developer. If available, source code is consistently and clearly commented and source code naming conventions are adhered to consistently.

SML3 - Use is possible by most users: There is external documentation that describes all API functionality, human computer interface (HCI) and code modules, which is sufficient to be used by any developer. There is an extension guide that provides information on how to customise and add plug-ins to the software. If available, source code documentation is sufficient to allow an experienced developer to understand program flow and logic with moderate effort.

SML4 - Software is usable: There is a guide to the documentation and how to use it. There are examples of how to use the API & HCI for different use cases, and materials & tutorials can be used to train other developers. Documentation is consistent with the current version of the software.

SML5 - Demonstrable usability: All stages of the software development lifecycle are fully documented, including design, testing and future improvement planning. Documentation is appropriate for different categories of users. Documentation is consistent with the current version of the software. User created documentation and comments form part of the available documentation.