Git repository documentation Standard

Do not index

Primary Keyword

Lié à Analyse sémantique (Articles liés) 1

Lié à Analyse sémantique (Articles liés)

Statut rédaction

A améliorer

Lié à Analyse sémantique (Articles liés) 2

Documentation structure README : Landing page of the documentation Overall architecture presentation Prerequisities & basic interactions / First steps Services / Modules / Folders / Sections / etc Support operations Miscellaneous External links Example for an infrastructure repository Remarks

Documentation structure

README : Landing page of the documentation

File: README.md and docs/README.md (symlink of README.md)

File content:

Table of content of all the documentation

Overall architecture presentation

Aim: to provide a high-level vision of the repository, what is its purpose, how is it integrated with the other services, when is it needed to interact with it, etc

File: docs/10_introduction.md

File content:

What is the purpose of the repository

What can we find in this repository

What are the different files and folders of the repository

Where to add code? I.e. the different environments, services, etc

What is the purpose of the deployed service? What are the major provided services by the actual code? (data collecting, computing, etc)

Prerequisities & basic interactions / First steps

Aim: to understand how to interact with the repository, but not as a consumer of the project, but as a developer. For an infrastructure it might be how to connect and how to deploy some resources, for an application it might be how to retrieve the secrets and how to run it on local host. Informations relative to the deployment are to include here as well. I.e. how the release system is working, if it’s built automatically, where? when? how? etc.

File: docs/20_prerequisities-basic-interactions/README.md

Examples of files :

Okta (File: docs/20_prerequisities-basic-interactions/okta/README.md)

Connection With Okta (File: docs/20_prerequisities-basic-interactions/okta/connection.md)

Retrieve credentials (File: docs/20_prerequisities-basic-interactions/credentials.md)

Interact with Azure CLI

Creation of a local environment

Plan and apply changes to the infra, where is the state stored

How to create and deploy a new release (with the help of CI/CD)

Decrypt Ansible-Vault files

Add new Ops users to the repository (for newcomers)

Services / Modules / Folders / Sections / etc

Aim: to interact with the deployed services, or with the codebase modules, how to install/update/troubleshoot them. Here we present each service and its associated use-cases. This section is the major part of the documentation. It documents all of the modules, or the services, or the sections, etc. For an infrastructure, it might be the different accounts and the different layers, as well as the different services. For an application, it might be the different modules and their exposed APIs, the different abstractions, etc.

File: docs/30_services/README.md (or 30_modules, or 30_sections, etc)

Examples:

<service> (File: docs/30_services/<service>.md)

Installation (Section one: Installation)
Update (Section two: update)
Backups
Useful processes to know (i.e. how to update a K8s cluster)
Troubleshoot and recurrent issues (i.e. expired certificates)

If the file gets too long, it is possible to split it:

<service> (File: docs/30_services/<service>/README.md)

Installation (File: docs/30_services/<service>/installation.md)
Update (File: docs/30_services/<service>/update.md)
Backups
Useful processes to know (i.e. how to update a K8s cluster)

Bastion (File: docs/30_services/bastion.md)

CI/CD (as a consumer: what are the available workflows)

Github Runner (as a provider: how and where is it deployed)

Kubernetes

Support operations

Aim: to provide fast all the support operation procedure for ops teams

File: docs/40_how_to.md or docs/40_how_to/README.md

Miscellaneous

Aim: placeholder for documentation that doesn’t fit in any of the above sections, note that this section should be as empty as possible

File: docs/40_miscellaenous.md

External links

Aim: to provide links to useful documentations that are not directly related to the actual repository. I.e. links to Philips documentation

File: docs/50_external-links.md

Example for an infrastructure repository

README.md

What is the purpose of the deploy repository?

What can we find in this repository?

(everything from the first section of this article)

docs/README.md

Symlink to README.md

docs/10_introduction.md

docs/20_deployment-and-entrypoints/README.md

Connecting with Okta (File: docs/20_deployment-and-entrypoints/okta.md)

Note that this could be a link to the docs/30_services/okta.md#processes-how-to-connect-in-a-terminal

Credentials, AZ CLI, etc

local environment, run plan&apply, etc

(everything from the second section of this article)

docs/30_services/README.md

exhaustive list of the deployed services, with a single-line description for each of them

docs/30_services/cicd.md

What are the available workflows?

Where is it running (link to github-runners.md)

docs/30_services/github-runners.md

Where are they deployed? How are they configured?

What are the available runners? (link to packer.md)

docs/30_services/okta.md

(example, but do it for each service)

Installation, Update, Backups

Useful processes (i.e. how to connect to AWS in a terminal) and troubleshooting

docs/30_services/packer.md

Images that are created

Where are they stored, how are they built

What are they used for (links to CICD and Github Runners)

docs/40_miscellaneous.md

Keep it as empty as possible

docs/50_external-links.md

Keep it as furnished as possible

Example for the different Terraform accounts and layers

docs/30_services/infrav2/accounts/shared-services.md

Describe what are the resources deployed in this account, and what are the different layers that are used. For each of these layers, don’t describe what they deploy, but what are the given parameters (think of them as functions, here we describe the function call, not the function body)

Here the documentation won’t describe how the layer works, but will only describe what it gives as variables (and possibly how it impacts the deployed resources). It is advised instead to provide links to the layers.

docs/30_services/infrav2/layers/ses.md

Describe what are the resources created by this layer, describe the variables it receives, what they accept as possible values, and how it impacts the deployed resources (i.e. enable_bastion = true creates a group of resources).

Think of the layers as functions, here we describe the function body, and how the given parameters can influence what it deploys.

Remarks

If a documentation can fit in multiple sections, it’s better to put it along the service it’s deploying rather than where it is deployed. Then links should be added to the where is it deployed section. I.e. Github runners can go in both CICD and Kubernetes, so they should go in CICD (what is deployed) rather than in Kubernetes (where is it deployed). Adding a link in the K8s doc is a good idea as well

The more are the doc articles linked between themselves, the better. Don’t hesitate to add a useful links section at the end of each document with any link you might find useful to keep

Concerning processes, it’s better to have one and only one way to do things. Keep things clean, and don’t add useless abstraction. The goal is to know what’s going on and be able to debug it easily if it fails

When there are commands to run, make it copy-paste-able. This means that if some variables are required, set them at the beginning of the article then just reference them. The goal is that a reader can just copy-paste each line and that it works out-of-the-box

Don’t hesitate to be too verbose. Add links to specific portions of the codebase, show sample outputs of the commands to run, the more a reader has context about what’s happening, the better

Keep docs updated as much as possible, if there are links to actual code, add a preview of the file instead of copy-pasting it

One could add a daemon checking periodically for dead links in the documentations?

One could add another job in the GHA workflows checking that the doc is modified for each PR?

To migrate the existing docs, a big job is to arrange the current documentation (moving files), and integrate the existing READMEs accordingly. I.e. the deploy/infrav2/okta/README.md should go in deploy/docs/30_services/okta.md and be linked in deploy/docs/20_deployment-and-entrypoints.md