Guidance about types of documentation

[galund]

As a newcomer to GDS or as a managed service provider (or as a team planning some substantial new work)...

I need to know what kinds of documentation should exist... and what guidance is relevant for the content therein...

so that my documentation follows GDS best practice... and so there is familiarity/consistency when technologists want to learn about what other teams and programmes are doing.

Broadly we have (at least) the following types of documentation:

• customer-facing documentation (eg for government services integrating with our platform products)
• architectural decision records (ADRs)
• architectural designs and specifications (in some programmes captured as RFCs)
• 'team manual' documentation, perhaps including 'run books' for incident management (note the contents of this documentation may in fact apply across multiple teams especially within a large programme)
• non-technical documentation (especially introductory material) for onboarding into programmes (we should be clear what is in scope here vs the GDS wiki and any other DSIT intranets)
• internal documentation and ways of working (often applicable to a single team - in smaller programmes may not be distinct from the 'team manual' type of documentation)

(any more?)

For each of these kinds of documentation we may be able to reference guidance about relevant points from the service standard/TCOP, common GDS practices (or at least list out some of the things we do in various programmes) and maybe offer some advice about style, technical writing, content design, etc.

[galund]

Arguably the main distinction here is between internal documentation vs external-facing documentation. But we can also have opinions about how we work in the open vs when internal docs should be restricted to GDS staff, and what processes/practices we prefer for certain use cases. And the guidance about what good looks like would be nice too, if we can gather what folks across the org think that is :)

(Edit: tool recommendations will be a separate issue.)

[p-berkeley]

I'd say the page we talked about Writing/storing/sharing technical documentation should probably be the same as this? Something along the lines of a heading like this (thoughts very welcome):

How to Write and Share Technical Documentation

You should consider your users (developers/technologists) and sensitivity when creating and maintaining documentation.

Technical documentation should be as clear, concise, and transparent as possible, so that it doesn’t hinder people from doing their jobs. You should consider the following principles when documenting technical information:

Avoid Duplication. Ensure that technical documentation does not overlap with existing content. If there is existing documentation on the same topic, either iterate upon it or reference it instead of duplicating.

Adhere to the GDS Way. Document on the GDS Way if possible. If the documentation cannot be made public, identify an appropriate cross-GDS site for storage. If it cannot be shared with all GDS staff, ensure it is included in a relevant team manual or similar.

Manage and Update Efficiently. Establish a clear plan for storing and updating documentation. Utilise the 'docs as code' approach where possible, and determine whether ownership should be assigned to an individual, a team, or a Community of Practice.

Meet Service Standard Principles. Ensure that your documentation aligns with principles 1-5 of the Service Standard.

Keep documentation secure. Follow guidance on Government Security Classifications and ensure you have followed your business unit’s security policies when creating and maintaining docs.