Executive Summary
We are proposing to put in place a Documentation Hub, ACCESS-Hub, powered by MkDocs. ACCESS-Hub will provide links to the documentation supported by the ACCESS NRI and any documentation the ACCESS community deems useful. It will group and clearly identify which documentation is supported by the ACCESS NRI and that supported by the community.
The technical documentation supported by the ACCESS NRI will either use ReadTheDocs (RTD) or MkDocs + GitHub pages. ReadTheDocs is preferred for automated API documentation, or strict versioning is required. MkDocs is preferred when the barrier to contribution needs to be as low as possible. Other documentation will make use of other tools and platforms as appropriate for the type of communication (e.g. Jupyter Notebooks and Books, YouTube, etc.).
See below for a summary of how the proposed strategy complies with the identified requirements
| Criteria | Compliance |
|---|---|
| Limit the number of platforms for supported documentation | MkDocs + GitHub pages and RTD |
| Clear delineation between NRI curated and community-led organisation | Separate community GitHub documentation |
| Clear separation of supported and community docs on ACCESS-Hub | |
| Documentation contained within a model code repository | Docs in model repo where possible subject to licensing |
| Contributions from a wide range of people: NRI staff and the community experts | Publicly visible git repository allows input via issues and pull request |
| ACCESS-Hub conduit for community contributions | |
| Support of code snippets | Code snippets supported by all plaforms |
| Standalone documentation with its own versioning if required | RTD versioning is tempo customisable |
| Support a limited range of formats for NRI supported documentation | Sphinx very widely used. Other systems can generate compatible docs if required e.g. jupyterbook. Otherwise default to Markdown |
| Ease of use by the community | GitHub issues and pull requests are well known and currently used in community |
| Markdown is a simple and easy to use markup language that is very widely used. e.g. GitHub | |
| ACCESS-Hub can link to documentation in any form. So documentation software systems with lower barrier of entry can be used if necessary |
Introduction
ACCESS-NRI (NRI) has a requirement to provide documentation to the community as a component of release packages. Some of that documentation will need to be sourced from the community, who are the domain specialists.
The NRI can also play a very important role by providing a common location for other related documentation generated by the community.
There needs to be a clear distinction between documentation supported by the NRI, and other documentation that is not supported but is recognised to be of value to the community.
Requirements for the Documentation
NRI Supported Documentation
All release packages require extensive documentation. This documentation can be broken down into two broad groups:
-
User focused documentation: describes how to use items in the release package, such as running models or analysing model output data. This category includes any documentation produced for training purposes. As such it can use a wide range of formats to support different types of communication (e.g. code-based, video, text).
-
Technical documentation: describes technical detail that is of interest to a narrow audience with specialist knowledge. This can be further subdivided into
- Versioned documentation that resides in the same repository as model component code, and is updated in lock-step to reflect changes to the code
- Other technical documentation that is less closely tied to rapidly varying and versioned codebases, e.g. documentation relating to the generation of input data such as bathymetry
- More general documentation such as policies and practices
It is important that versioned technical documentation is identifiable by version, so that it is straightforward to find the technical documentation that relates to an exact version of a model. This also ensures versioned technical documentation does not become stale or out of date as can happen if a single documentation source is used to cover all model versions.
Other technical documentation exists on an update cycle that is not necessarily strictly tied to code changes. Such as example python notebooks and general How-To guides. These items will need to be periodically updated and will have their own versioning tempo to facilitate updates and backwards compatibility, but it is unlikely to change with the same rapidity. This documentation may only need to be revised with major model or configuration updates and may share some of the same version numbers as models or configurations to which it is closely aligned but will likely have many fewer total versions. This makes it easier for users to ensure they are using the correct version of the documentation.
More general documentation does not require formal versioning.
It is essential that the community can easily provide feedback on the documentation and propose changes. Current documentation work by the NRI must also be clearly visible to the community.
Versioned technical documentation will be the industry standard ReadTheDocs, otherwise MkDocs + Github Pages as this is simple and easy to use, lowering the barrier for community input. This means all documentation supported by the NRI will be hosted in public git repositories, either within a model component repository or a standalone documentation repository. It will allow the community and the NRI to communicate on the state of the documentation through the same issue process as for the model development work.
Community Produced Documentation
There is immense value to the broader community to have a single curated location for documentation beyond what is provided and supported by the NRI. There is also value to the NRI, as a source of information from the community, who are domain specialists.
Much of the community produced documentation exists in many different formats, on a variety of platforms, such as wikis and legacy websites, that do not have a guaranteed long-term future. Documentation that has value for the community will need to be migrated to a stable platform.
The NRI needs a solution that provides clear delineation between NRI released and supported documentation, and community produced documentation that the NRI has neither the remit nor resources to actively support. We also need a solution that does not impose an undue burden on community members that do not have the time to spare, as this would limit community engagement.
Requirements summary
| Category | Requirements |
|---|---|
| General requirements | Limit the number of platforms (ideally 1). |
| Clear delineation between NRI curated and community-led documentation. | |
| Technical documentation -- versioning in lock-step with model | Documentation contained within a model code repository model |
| Contributions from a wide range of people: NRI staff and the community experts | |
| Support of code snippets | |
| Technical documentation -- with own versioning | Standalone documentation with its own versioning tempo |
| Support a limited range of formats | |
| Contributions from a wide range of people: NRI staff and the community experts | |
| User focused documentation | Standalone documentation with its own versioning tempo |
| Support a limited range of formats | |
| Contributions from a wide range of people: NRI staff and the community experts | |
| Community-led documentation | Ease of use by the community |
| Support a wide variety of formats |
Proposed Strategy
The proposal is for ACCESS-Hub: a central one-stop-shop for documentation, where anyone can go and quickly find links to either NRI supported documentation or community produced documentation.
The ACCESS-NRI website will have an obvious link to ACCESS-Hub, but the hub will be a git-based Material for MkDocs + Github Pages site for a number of reasons:
- More responsive to update than the website
- Best practice versioning with git
- Open to the community: anyone can lodge issues if there are errors or updates and propose updates through pull requests
- Curated by the NRI, which makes documentation visible and credible
- Platform agnostic: only consists of links to existing websites, no direct hosting of community documentation
- Markdown is simple to write, lowering barrier to contributions
- Github Pages is easy, and is clearly associated with the GitHub repo where changes are made
- Material for MkDocs has an excellent built-in live search capability
Links to documentation will be clearly sorted into NRI supported and community documentation. In addition, there will be further separation into broad categories, perhaps aligned to working groups. Entries will be annotated to indicate the nature of the material, and Material for MkDocs has excellent live searching which allows for discovery via the annotations.
All the documentation supported by ACCESS-NRI will be created under separate sites on the main ACCESS-NRI GitHub Organization and linked to from the ACCESS-Hub.
Community produced documentation can be hosted on any platform chosen by the community since the Hub approach has the advantage of being platform agnostic, which means it will be relatively quick to create.
Having ACCESS-Hub in a GitHub repo site makes updates easy and open to the community. This aligns with agile philosophy: create a product as quickly as possible and then iterate and improve. It also scales well, with little additional overhead for adding links to more material.
ACCESS-Hub will make gathering information for NRI supported documentation easier, which is a key objective. In some cases, large sections of existing documentation will be able to be reused, or transferred, to the NRI supported documentation.
One possible downside is a lack of consistency between community generated documentation, both in quality and format. However, the NRI will showcase best practices for documentation, which can be emulated. Excellent community sourced documentation will also act as exemplars for the broader community. Included in the ACCESS-Hub will be instructions on how to contribute and suggestions for documentation platforms that are suitable, including software solutions for those for whom MkDocs would be technically challenging and present a barrier to community involvement.
There may be some legacy documentation that is valuable to the community but is no longer supported or maintained and in danger of disappearing. Depending on value, and difficulty level, it may be possible for the NRI, or the community with NRI assistance, to transition legacy documentation to an RTD site, or similar. However the NRI will explicitly have no role in on-going support.
As part of this strategy ACCESS-Hub will be hosted under it's own community ACCESS-Hub GitHub Organization where community generated or legacy documentation can also reside. This provides a host for any community documentation that has no other obvious location, or if the community sees value in hosting their documentation in a shared space. Having a separate community GitHub organisation simplifies administration and permissions compared to hosting community resources on the main ACCESS-NRI GitHub Organization. It also provides a focal point for collaboration and community building around the ACCESS-NRI.
Strategy compliance
Refer to the Executive Summary for a table outlining how the proposed strategy complies with the stated requirements.