As an engineer, I tend to error on the side of “this should be documented”. However, I think that with the recent push of being agile and lean, the word “documentation” has a bad connotation that comes with it.  I never realized that people might have a different definition of the word “document” than I had.

Here recently, I’ve been working on training a group of developers that work with one of our clients.  I started off showing them all of the product’s documentation…SDD, PRD, SRD, UIRD, and other acronyms that mean a lot to some people, and very little to others.  I made a point to show them the documentation to begin with, before diving into the software itself.  (This was mainly done to show them what documents to expect changes from the client in.)

Sometime later during the 4 weeks of training, we began looking at an engineering tool that we created internally.  This tool had very VERY few in-code comments.  This tool was not intended to be maintained, nor was it expected to be seen by others.  It looked pretty bad, and was difficult to explain what some of the longer functions did, without combing over each line of code.

The day after we trained on this tool, I mentioned that they might want to begin documenting the tool if they found themselves using it more than the 1 week we used it during training.  Then a LOADED question was asked….”what format should we document this tool in, and should the document be in the PLM (Product Lifecycle Management)?”

Well, that’s when I realized that my definition of “document the code” and their definition were not the same.

Summarized into my own words…

Software Documentation:  Low/High level DETAILED documentation, often referred to as a manual.  I typically think of this as a document that lives in some sort of configuration management tool.

Annotation:  explanatory comments added to your work after you’ve written it.  I typically think of this as in-code documentation.

So, back to the question…to document, or not to document?

Since we have been changing into this much more agile and lean group, perhaps we should change our lingo as well?  Moving forward, I believe I will use the term “annotate”.

There are other places where such lingo is changing.  I am challenging myself to be more mindful of these changes; and more importantly, to implement them when speaking with others.