Why are developers alergic to documentation?

On a Wednesday weak and weary, as I coded eyes so bleary…

As I was familiarizing myself with Glide this afternoon my thoughts once again turned to developers aversion to documentation, not picking on Glide in particular it was just happened to be the thing that got me opining this afternoon. As I was discovering how the drop down box worked I got to wondering in how many other fields the end product is considered self documenting.

Imagine if you will (read in your best Twilight Zone voice), an airline pilot trying to learn to fly the latest Boeing jumbo jet and he wants to know how the flaps should be set for take off. Boeing says, “Oh, here are the blueprints”, or “Just look at the plane.”, or “You can get an idea how to set the flaps by looking at this example on the 787.” This would not happen of course, the pilot will have the information the pilot needs available in a form that best suits the pilot, likewise the planes mechanic will have a need for different set of information and it will be available in the form that best suits the mechanic.

While I’m not a professional developer I have done professional C++ development as part of a team and one thing that always bugged me was that I would get a request for a particular feature that did ‘A’. After implementing this feature someone else said ‘Oh, I thought that feature should work like B.’, or a bug report would be generated when all the time the feature was working like ‘A’ like it was originally requested. Finally I wrote up a document, just a table really, of program features (tools, buttons, etc.) and what they were suppose to do, not really form a coding point of view but from a usage point of view with insight as a developer (i.e. the ‘Blur’ button will apply a Gaussian filter to the bitmap). This solved so many problems having it spelled out in advance how things should work (not how they were implemented).

Since I work on a wide variety of research projects it might be 6-12 months between times when I look at a piece of code so I tend to leave a LOT of comments in my code about what I was trying to do and/or why I did something a certain way, i.e. “I had to do this section this way as a work around to a bug in library ‘X’ .” Then when I revisit the code a year later I know not only what I did but why.

I used to always label files for small snippets of test code something clever like “Test 1”. Several years ago a friend chided me for doing that as you can’t go back and look at the file name and know what that code was for. Do you need to keep it? What were you trying to accomplish. I know many times I have tried a few different ways to accomplish something and then alter on had a use for one of the alternative methods in another project and it is hard to find with a clever name like “Test1.cs”. I still do this and have to keep reminding myself not to, in fact the test project I was working on just now is called “NETMF_Test1” which was silly.

Anyhow I’m just pontificating instead of accomplishing actual work :slight_smile:

1 Like

By the way, if you’re not using the new “docfx” tool to generate your documenation, you’re doing it wrong.


Yes, if you markup your code properly tools like that can help. It still only tells you what you did not why you did it that way or what you were really trying to accomplish. My point was that ‘self documenting’ is a pipe dream at best IMHO.

@ Jeff_Birt - Certainly true. That’s why DocFX lets you build “conceptual” documentation right alongside your “code-derived” documentation, and link back and forth between them. Think MSDN, where there are API references, as well as other documentation that explains general concepts.

Oh, and another killer feature: DocFX lets you use ACTUAL CODE as the samples in your API reference documentation. This way, your refactoring will update your code samples. I like to use unit tests as the samples (or strategically chosen chunks of tests, anyway), because that way I can be quite confident that the code sample not only compiles, but actually WORKS.