OK I need to say this out loud to somebody to make sure I am actually saying it:
-
OK I need to say this out loud to somebody to make sure I am actually saying it:
There is no good reason to leave procedural knowledge contained only within people's heads.
Example: If Group A has a manual process like "need to stop and ask Group B because 'they just know' the answer to this step", then Group B contains an island of knowledge.
That island needs bridges built instead of sending messages in a bottle. A bottle that carries the same data that we would interact on a bridge, but it takes a LOT longer, fraught with error.
There are so many reasons documentation is important. Being a guardrail and reference for people who have a disability doesn't seem to be a good enough reason for some to encourage that documentation be done.
So, if not for usability, can we make it for knowledge management and organizational archaeology? How many times have we said to ourselves, we don't know how that works because so-and-so left the company? Or the whole team did?
Documentation is not an extra. Documentation is a muscle. It is one of the Eight Principles of Production Readiness. Documentation gives us our history. It is something that we can look back on, notice our mistakes, how we overcame adversity, how failure helped us keep learning. How our successes developed and emerged the system. How the complexity changed, simply because documentation did (or did not).
We cannot contain all this knowledge to spoken culture. We MUST consider how everyone has access to that knowledge and how they are able to interpret and understand it in order to use it and be great in their work.
The constant push back on creating good documentation is beginning to get on my nerves. If you can't tell.
In my best Steven Jessie Bernstein:
~~~ THANK you for reading DOCS!! ~~~
#SRE #Documentation #ProductionReadiness #KnowledgeManagement #IslandsOfKnowledge #KnowledgeSiloes #TribalKnowledge #KnowledgeCulture
-
Adrian Cockcroftreplied to craquemattic 🏳️🌈 last edited by
@dtauvdiodr Make notes for yourself on a wiki page, as you encounter things you think should be written down, don’t spent too much time on it or making it pretty, but track traffic to it. Don’t tell your manager it’s documentation. Other people will end up using it, so you end up with evidence supporting your position.
-
craquemattic 🏳️🌈replied to Adrian Cockcroft last edited by
@adrianco Excellent advice!! Thank you. I've been doing some of that already merely because docs are part of my workflow.
In general, I like fostering this ability to work at the grassroots. This week I started up my weekly "everything SRE" session, and the way I have built fandom in the past is to make it really useful and collaborative, and then people just end up attending on their own volition.
-
Adrian Cockcroftreplied to craquemattic 🏳️🌈 last edited by
@dtauvdiodr Yes. “To ask permission is to seek denial” applies here. The key thing is don’t keep useful notes privately, put them in your personal wiki space, and edit them during your SRE session as things come up, so that people see that it’s there. But don’t sell or structure it as docs, let it sell itself.
-
Adrian Cockcroftreplied to Adrian Cockcroft last edited by
@dtauvdiodr One thing we did at Netflix was to avoid a lot of documentation by writing code. No run books, Python automation. That might make your manager happy. If it doesn’t then I expect you will get a new manager sooner rather than later…
-
@adrianco @dtauvdiodr I've taken that approach at my site by pushing Ansible pretty hard the last few years. We have a handful of very bespoke systems so scalability isn't a problem, but knowing how to build and maintain them was. Any "why" docs can be put as comments in yaml and Jinja which works great. We know the docs are accurate because we run them.
-
@raven667 @dtauvdiodr Yes, exactly that. The issues come if you get into ownership/turf wars with teams that don’t want you automating their stuff for them, but are maybe ok with you documenting them.
-
@adrianco @raven667 @dtauvdiodr
Have y'all seen Yore? I saw a one liner about it but sounds related maybe: https://pawamoy.github.io/yore/