Often in a large enterprise you will need to submit changes to a CAB (Change Advisory Board) before getting approval to make any changes to your infrastructure. But managing versions of your diagrams and documents / infrastructure code / what has actually been deployed can be difficult.

Documentation is often stored in a seperate document store (like Sharepoint).

I’m using Azure DevOps to manage work items here, but you can insert your own (Jira, Github Issues).

Our plan today

1. Problems to address
2. Solution
3. New document creation process
4. Diagram
5. Results

1. Problems to address

• Separating documents from infrastructure code often causes documents to be out of date as they’re not always up to date in Sharepoint.
• Decisions of when/why changes were implemented is hard to keep track of.

2. Solution

• Store documents within Git (Source Control), directly with infrastructure code.
• Utilise Pull Requests in Azure DevOps for CAB approval of document changes (and track any changes that have been requested to the documents).

3. New document creation process

• Each application folder has a docs folder (with LLDs, HLDs, Visio diagrams, etc)
• An Engineer will have a Story in Azure DevOps to do the analysis and design work and create the document
• They will create a branch to make the changes to the documents in that folder, commit the branch and submit a Pull Request when they are complete.
• When a Pull Request is requested to master, a release pipeline copies the docs folder to the folder in Sharepoint.
• The PR is assigned to a CAB member for CAB.
• They then take this to CAB, and can view the documents in Sharepoint or in the repository.
• If approved this is merged into master, and the new story can be created for the next sprint to do the implementation.
• If denied, they CAB can create bugs against the Pull Request in Azure DevOps, those can be assigned to the engineer who can make the changes and the docs folder will be copied again to the Sharepoint folder

4. Diagram

5. Results

• Versioned documents and code are stored together at the same time.
• Any time code is changed you will see if documentation hasn’t been updated and also know what actually changed.
• Part of the Pull Request process for committing code, can be to ensure documentation has been updated if needed.
• All conversations around the document changes will be visible inside the Pull Request. Comments can be seen / discussed inside the Pull Request, and bugs created and assigned for any changes needed. (This will show us approved date, and will see the who/when decisions were made to make changes)

6. Conclusion

Now we have documentation and infrastructure code stored together and versioned in the same location.

Next post will be setting this up in Azure DevOps or maybe GitHub actions.

What do you think of this approach?

How do you store your documentation for you infrastructure code?