Skip to content

Where are the documents at?

New Guy in Infra Team: Can I get the build & design documents please ?

Old Guy in Infra Team: uh, We don’t have one, We follow agile, So “no documentation”, & we follow Devops so you will find everything is infrastructure as code..

New Guy in Infra Team: sigh.. Not again..

Questions for these “Old Guys in Infra Team”:

  • Does management understand IAC?
  • Can IAC be used for presenting the current state to sponsors?
  • Will Sop‘s get interpreted using IAC?

I am sure most of us at some point would have hit the above scenario, personally i have once and for the new guy it is literrally ‘Not so expected moment’. I am writing this article to share my point of view which most of the “Old guys in infra team” following Agile/DevOps might disagree to, but at some point they need to understand what intellectual property is & how valuable it is for any organisation.

What a myth, agile means no documentation ? or DevOps culture means no docs? well, i think this is really a big debate but i would definitely point out an article by Leanne Howard which I like a lot.

DevOps provides an amazing opportunity for the team to continuously manage & update documents using automation. Even if IAC concept is used for long running environments or a constantly changing dynamic environment, It is just matter of detecting changes in current state config that matters for the organization & triggering a new build document.

Lack of documentation not only increase the time taken to onboard new engineers but creates lack of intellectual property for an organisation.

So, why not use continuous documentation or document as code?

For continuous documentation, i would recommend reading to‘s report which talks about continuous documentation, which clearly explains the governance & best practices.

For Documentation as code, I took out couple of hours and wrote a prototype called Odit for Microsoft Azure which can be extended for any cloud provider. I used this to test and constantly update a build document using Jenkins, worked as expected, Each time I add, change or delete resources my build document gets updated with the current state of infrastrcuture.

Documentation as code.

My recommendation is to use documentation as code, writing the custom code to generate document would take comparatively less amount time than creating or updating a document each time the state of infrastructure changes.

Thee Code Dragon

Source: Linkedin Article

Leave a Reply

This site uses Akismet to reduce spam. Learn how your comment data is processed.

%d bloggers like this: