5. Documentation

Note

Indicator Requirement: "Digital public goods require documentation of the source code, use cases, and/or functional requirements."

---

For this indicator, you must provide detailed documentation of your digital solution. Below are recommendations for each DPG category.

Open Software

For Open Software solutions, documentation could include an open repository, technical specifications, functional requirements, etc. that would allow a technical person unfamiliar with the project to launch and run the software. It is important that the documentation shows the following aspects (non-exhaustive list):

• How to install the project (local environments, testing, code runs etc).
• How to fork the project (forking, patching, contributing upstream and downstream).
• How to deploy the project as a user.
• Any additional context (both technical and non-technical) that could help a user or a developer navigate through the project.

Below is a list of common sections or types of software documentation:

• Overview: This gives a brief introduction of what the software does, how it works, and who it is for.
• Architectural Diagrams: This shows the structure, components, and relationships of the software, using visual diagrams and descriptions.
• Technology Stack: This lists the technologies and dependencies used in the software, and their versions and compatibility.
• Installation Guide: This explains how to install and run the software in different environments, such as local or production.
• User Guide: This teaches the end-users how to use the software, and may include a FAQ section.
• Release Notes: This section follows semantic versioning, and records the changes and updates for each version of the software.
• Contributing Guide: This section provides guidelines on how to contribute and participate in the software project.

Tip

For all the examples mentioned above, you can explore these open source documentation templates from The Good Docs Project. The templates and accompanying guides will help you create quality documentation faster and easier.

Open AI Systems

For Open AI Systems, documentation includes having documentation for the AI models, data sets, and software components.

• For the dataset component, this documentation should include the context, sources, methods of generation for this data, limitations, and potential use cases.
• For the AI component, the documentation should include details about the machine learning or deep learning components and the technical resources needed to execute or modify the AI locally.
• For the software component, this documentation should include both technical and non-technical aspects that can enable a layperson to run, deploy, fork and modify this project.

Typically, the documentation for the AI model's software component expands on the documentation requirements outlined above for Open Software by describing the technical aspects, such as:

• The technology stack or platform that the AI products are launched on, and the technical requirements for different activities, such as GPU type and computing power.
• The data types and formats that the project should work with, the model architectures, the learning parameters, the transfer learning process, and the learning curves.
• The evaluation and testing methods for the project results, such as the metrics used to measure loss and accuracy.
• The integration guide for the product offering with other existing or potential software systems.

Open Data

For Open Data solutions, documentation must include enough descriptive information to ensure easier use. Data that has been well documented is recognisable, comprehensible, and usable in the future. You should record your data at each stage of the research or data collection process. The table below describes some general guidelines from the Missouri S&T University Libraries recommended for aspects of datasets that should be documented.

Title	Description
Creator	Names of the organization or people who created the data.
Identifier	Number used to identify the data.
Subject	Keywords or phrases describing the subject or content of the data.
Funders	Organizations or agencies who funded the research (if applicable).
Rights	Any intellectual property rights held for the data.
Access information	Where and how the data can be accessed.
Language	Language(s) of the intellectual content of the resource, when applicable.
Dates	Key dates associated with the data, including project start and end date; release date; time period covered by the data; and other dates.
File Formats	Format(s) of the data, e.g. FITS, SPSS, HTML, JPEG, and any software required to read the data.
File structure	Organization of the data file(s) and the layout of the variables, when applicable.
Variable list	List of variables in the data files, when applicable.
Code lists	Explanation of codes or abbreviations used in either the file names or the variables in the data files (e.g. '999 indicates a missing value in the data).
Versions	Date/time stamp for each file, and use a separate ID for each version.
Checksums	To test if your file has changed over time.

Open Content

For Open Content collections, this should include all relevant/compatible apps, software, or hardware required to access the content collection, and instructions regarding how to use it. A good way to provide evidence of this is:

• Provide a link to a section of your user guide that explains how users can access the content.
• Provide a link to where you state any technical requirements for accessing the content.

---

Tip

Here's a collection of extra resources and helpful links curated by the DPGA and the DPG community you can explore or contribute to.