Open galund opened 1 month ago
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.)
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):
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.
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:
(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.