Skip to main content

The unwritten rules of DevOps

Well obviously they are written down now! But these originally started off as a internal riff on the self obvious truths that every professional DevOps engineer should know. Since not everyone had been working in DevOps as long as the more seasoned members of the team we wrote them down to reinforce them as some of the basic truths of DevOps.

  • The answer to any question that is asked twice should be documented.
    • For those that choose to use the search function in your documentation tool, (we used Confluence), the answer should be easy to find as long as the article is well categorized and tagged.
    • For those users who chose to ask in chat, the URLs to such questions are just a few clicks away for those in the know to send them a link, honestly I should have remapped a function key to the "Do I need a Jira for...?" article since I referenced it so often.
  • Documentation should be written such that any other member of the team can perform the task solely from the documentation.
    • Any documentation that requires a user with ordinary skill in the art to ask further questions is insufficiently documented.
  • Not all processes are worth automating.
  • But every manual process should be fully documented at the very least!
  • Documentation needs to be reviewed and updated on a periodic basis. When documentation reaches its expected end of life, it should be clearly marked as deprecated and moved into a folder where it can be referenced if such a need ever arises.

Reddit - What does "good" documentation look like?

You get hit by a bus, someone coming in can make things work.