About the Documentation¶
The documentation is a central pillar of how we provide support for our services. This page provides 'documentation about the documentation'.
Diátaxis¶
The contents of the documentation are laid out based on the principles of Diátaxis, a systematic approach to technical documentation authoring. Briefly, every published page attempts to address one of four distinct needs:
- Tutorial: learning by doing
- How-to guide: achieving a specific goal
- Reference: looking up facts
- Explanation: understanding concepts
These four classes of documentation have a different purpose and are written with this in mind.
We use Diátaxis pragmatically to create and maintain high-quality, well-structured documentation, but are not afraid to compromise or use different approaches where a different approach is needed.
The FAQ pages are an intentional exception to this model — they provide a fast path for questions that don't fit neatly elsewhere, with links out to the relevant page for fuller detail.
Facility tags¶
On some pages, you will see a series of tags at the top of the page. These provide information to the reader about which BriCS facilities the page is relevant to. The facility tags provide flexibility for ensuring the overall body of information makes a coherent whole without compromising the overall structure to capture facility-dependent variations.
Contributions and corrections¶
The documentation repository is not available for general contributions. As a public and central pillar of our support services, it is important we keep close control of the content to ensure its quality and value to users. However, we do value input from our user community and users who wish to make a contribution are encouraged to raise a support ticket in the first instance.