Commentary

5 Types of Documentation

Each type of documentation has unique strengths and weaknesses. Knowing when and how to use each is an important skill for every developer.

Mike Wolfe

Nov 9, 2021 • 5 min read

"What was I thinking?!"

How many times have you said that to yourself while looking at old code? If you are working in a team–or a codebase that you inherited–you probably find yourself saying, "What were they thinking?!" even more often. And that's why it is so important to document your work as a developer.

Writing code may be hard, but reading code is harder.

Types of Documentation

As a developer, there are many different things you should be documenting: coding conventions, recurring processes, changes to code over time, and, of course, the code itself.

Not all types of documentation are created equal. They have relative strengths and weaknesses. The challenge is to match up the right sort of documentation with whatever it is you are trying to document.

Wiki

Your wiki is an ever-evolving reference for how to get things done within your organization.

(You could manage a wiki with a Word document or an Excel workbook. Of course, you could also carve pumpkins with a chainsaw. Neither is a good idea. Both are likely to result in big messes. I use DokuWiki, but a good no-setup option is also TiddlyWiki.)

The following things should be documented in your wiki:

Every recurring process
Standard operating procedures (SOPs) for your organization
Organizational coding conventions
How-to instructions (how to set up VPNs, etc.)

The following things could be documented in your wiki:

Application-specific developer documentation
Application-specific end-user documentation

The following things should not go in your wiki:

Instances of a recurring process

While you should document every recurring process in your wiki, the individual instances of those processes are better tracked in an issue tracker.

Issue Tracker (Bug Database)

This is where you document:

Bugs
Feature requests
Instances of recurring processes

One of the most important features of an issue tracker is a short unique identifier for individual issues. With FogBugz, all of our cases are available at a URL like this one: https://grandjean.fogbugz.com/?1234

We often add code comments like 'see FB 1234. This, combined with our standard AutoHotkey script, allows us to simply highlight the 1234 in the above code, press [Ctrl] + [Win] + [F] and AutoHotkey takes us straight to the associated FogBugz issue.

Here's the AutoHotkey code that makes the above convenience possible:

^#f::
AppsKey & f:: ;*** ;Universal FogBugz search on selected text
    text := GetHighlightedText()
    WikiCaseID := RegexReplace(text, "^\s*([wW]?\d+)\s*$", "$1", ReplacementCount)
    If (ReplacementCount > 0) {
        Run https://grandjean.fogbugz.com/?%WikiCaseID%
        If (SubStr(WikiCaseID, 1, 1) = "w")  ;case-insensitive check; matches both "w" and "W"
        {
            ; We migrated our wiki from FogBugz to DokuWiki; 
            ;     use the redirect page in DokuWiki to get to the new URL
            Run https://grandjean.net/wiki/gb/fb/%WikiCaseID%
        }
    } Else {
        text := uriEncode(text)
        Run https://grandjean.fogbugz.com/default.asp?pre=preMultiSearch&pg=pgList&pgBack=pgSearch&search=2&searchFor=%text%&sSearchFor=
    }    
    Return ;*
    
GetHighlightedText() {
    ClipSaved := ClipboardAll   ; Save the entire clipboard to a variable of your choice.
    clipboard =  ; Start off empty to allow ClipWait to detect when the text has arrived.
    Send ^c
    ClipWait 1  ; Wait for the clipboard to contain text.
    ClipText := Clipboard
    Clipboard := ClipSaved   ; Restore the original clipboard. Note the use of Clipboard (not ClipboardAll).
    ClipSaved =   ; Free the memory in case the clipboard was very large.
    Return %Cliptext% 
}

uriEncode(str) {
   f = %A_FormatInteger%
   SetFormat, Integer, Hex
   If RegExMatch(str, "^\w+:/{0,2}", pr)
      StringTrimLeft, str, str, StrLen(pr)
   StringReplace, str, str, `%, `%25, All
   Loop
      If RegExMatch(str, "i)[^\w\.~%]", char)   ;%
         StringReplace, str, str, %char%, % "%" . SubStr(Asc(char),3), All
      Else Break
   SetFormat, Integer, %f%
   Return, pr . str
}

Public Websites (Forums, StackOverflow, etc.)

If you are documenting some behavior that does not involve sensitive information and that could provide value to other developers, consider documenting it on a public website where other developers could benefit from it.

Stack Overflow is especially good for this as you can publish a question and answer at the same time, Q&A style. Here's an example that I posted years ago that I still regularly visit: SQL Server returns different record after insert on linked MS Access table.

UPDATE [2021-11-17]: Another option is to publish your own website and post your musings there (as I'm doing right now). I'm a little embarrassed I didn't think of this myself... (h/t @philivc)

I'm surprised that you didn't mention writing a blog post in the "Public Websites" paragraph.
Some texts on my website were written for the sole purpose of being a reference for future me.
— Philipp Stiefel (@philivc) November 10, 2021

Code Comments

Code comments play a special role because they are so close to the actual executing code. There is no context switching required. If you are looking at the code, you can't help but see the comments nearby.

The key to good code comments is to maximize the signal to noise ratio. Individual code comments should rarely be more than two lines long. If I need a longer explanation, I prefer to provide a short synopsis then embed a link in the code that jumps out to external documentation (either in a wiki or issue tracker or public website or code repository or... you get the idea).

This approach provides the best of both worlds:

The signal to noise ratio stays high within the code
A more in-depth explanation is just a click away

Version Control Commits

Clear version control commit messages provide context for your code changes over time. Version control changesets also maintain a record of who made the changes. This is an especially handy feature with multiple people working on a single project.

Having your code in version control also means that you can safely remove the parts that you don't need anymore, secure in the knowledge that you can always bring them back from the dead if the need arises. This helps boost the signal to noise ratio of the code that remains.