Self-documenting Artifacts

August 26, 2018

I believe in the value of documentation, but it takes extra effort to create and documentation easily gets out of sync with reality. There is plenty of discussion about this problem in relation to programming, but documentation isn’t just for programming, it adds value to all kinds of technical and business operations.

The programming solution is that code should be self-documenting. And then for sysadmin operations, the solution is to capture the sysadmin tasks in code. Programming has an “easy” solution because programming is about creating artifacts (code bases), so if a programmer has a collection of good artifacts, they don’t need any extra information, all the answers are right there in the code. The devops/sysadmin solution occurs naturally because the tasks lend themselves so easily to coding, so it makes sense to create an artifact to capture knowledge about what used to be a manual task.

The general solution is to find ways to turn all operations into a series of artifacts.

An easy example to think of is research. A good researcher knows how to find the information they’re looking for and they probably keep some notes as they go. If the researcher puts extra effort into formalizing their note-taking, then they can start creating a classification system for what they do in the research process, they can start formalizing research strategies and tactics, they can identify what information they’re utilizing at each stage in the research process, what information they’re looking for, and so on.

With the newly unearthed data about how they do research, the job can be broken down into a series of interstitial reports (a series of artifacts), and those artifacts can replace a good portion of “how-to” documentation that might otherwise be necessary to communicate the details of the job to someone new.

Some documentation is still necessary, but it can be more lightweight, like a few checklists or guidelines. The artifacts can do most of the heavylifting.

In my own experience, I’ve seen this idea succeed with both programming and writing operations. I’m sure many other business and technical processes lend themselves to the creation of self-documenting artifacts that can replace tedious documentation.

Tags: work programming