Self-Documenting Automation
There are two problems with documentation.
- It's the last step in many projects and nobody wants to do it so it's often "forgotten".
- The second you write a document, it's out of date.
Self-documentation solves both of these problems.
When we wrote our automation product, we wanted to make it easy for people to document as they go. We approached this with in three ways: Pretty Pictures, Annotations, and Comments.
Javadoc / Doxygen / pydoc
Javadoc and others pioneered the concept of putting documentation and code together. It is brilliant because now it's all part of the coding process. That means, it get done and stays up to date. And, there no separate "system" that keeps it. At all moves with the code.
Situate's Solution
With our product, Situate, we address the documentation problem in three ways and each are part of the workflow -- the thing people build when using our product. So, like Javadoc, the documentation moves with the thing you're building -- in this case, a workflow.
Pictures
A workflow is a picture. A graphical representation like a visio diagram (except our diagram really runs). Because it's a picture, even an untrained person can look at it and have an understanding of how it works. A picture not only shows what runs but in what order and so one can easily get a sense of structure, flow and order.
I like pictures because when I have to wake from dead sleep, I want a picture not code. Not to mention that I can't remember what I even did six months ago.
So pictures are self-documenting in that they show the structure, order and flow.
They are also good for to explain to management/the business. It's often hard to convey the complexity to someone who does not grasp it. Come on? How hard can it be? You get the file, you stick it in a database. Well, we all know it is never that simple.
Annotations
In our workflows, an annotation is a graphical element that is functionally inert but serves to docuement the workflow. A callout box with text that says, "if this breaks, call Dave" or "This must run as Administrator because...".
Background images can be used too. A background of a cloud that surrounds the AWS boxes distinguishes the fact that these boxes are part of the cloud. So in my head, I see... OK, this is where we go talk to the cloud parts. And better yet, since I know those are grouped that way, a network problem, might explain why there they are red flagged.
Comments
Liberal application of comments everywhere helps a lot. A description not only on a workflow but on each part of it. This way when a task fails, that comment can be part of the message the operator receives, part of the ticket opened in your ticket mangement system, and that memory-jogging "oh ya, I remember that..." moment.
But it does another thing too. It seeds search criteria. So if we're searching for keywords, etc., it's found.