> ## Content Index
> Fetch the complete content index at: https://nolongerset.com/llms.txt
> Use this file to discover other available public pages before exploring further.

# 5 Types of Documentation
- URL: https://nolongerset.com/types-of-documentation/
- Published: 2021-11-10T04:11:42.000Z
- Updated: 2026-05-08T13:01:19.000Z
- Description: Each type of documentation has unique strengths and weaknesses. Knowing when and how to use each is an important skill for every developer.
- Author: Mike Wolfe
- Tags: Commentary, Version Control, Signal vs. Noise, #Import 2026-05-20 02:59

"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](https://www.dokuwiki.org/dokuwiki), but a good no-setup option is also [TiddlyWiki](https://tiddlywiki.com/).)

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:

```autohotkey
^#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](https://stackoverflow.com/questions/5956689/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](https://twitter.com/philivc/status/1458332772574040065))*

> 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](https://twitter.com/philivc/status/1458332772574040065?ref%5Fsrc=twsrc%5Etfw)

## 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](https://nolongerset.com/signal-vs-noise/). 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](https://nolongerset.com/scraps-of-wood-and-code/), 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.

---

### External references

[dokuwiki \[DokuWiki\]![](https://www.dokuwiki.org/lib/tpl/dokuwiki/images/apple-touch-icon.png)![](https://www.dokuwiki.org/lib/tpl/dokuwiki/images/logo.png)](https://www.dokuwiki.org/dokuwiki)

[TiddlyWiki — a non-linear personal web notebook![](https://tiddlywiki.com/favicon.ico)TiddlyWiki](https://tiddlywiki.com/)

[GitHub - WaynePhillipsEA/twinbasicContribute to WaynePhillipsEA/twinbasic development by creating an account on GitHub.![](https://github.githubassets.com/favicons/favicon.svg)GitHubWaynePhillipsEA![](https://opengraph.githubassets.com/e8ef1fd3b90e05e5c7add80dbe63f4de1f98311c9cb930168e6b932f7bcd5b46/WaynePhillipsEA/twinbasic)](https://github.com/WaynePhillipsEA/twinbasic/)

[SQL Server returns different record after insert on linked MS Access tableWe recently upgraded our backend database from SQL Server 2000 to SQL Server 2008\. Since the switch we’ve had intermittent (read: impossible to consistently reproduce) and strange problems, but th...![](https://cdn.sstatic.net/Sites/stackoverflow/Img/apple-touch-icon.png?v=c78bd457575a)Stack Overflowmwolfe02![](https://cdn.sstatic.net/Sites/stackoverflow/Img/apple-touch-icon@2.png?v=73d79a89bded)](https://stackoverflow.com/questions/5956689/sql-server-returns-different-record-after-insert-on-linked-ms-access-table)

### Referenced articles

[Scraps of Wood and CodeResisting the packrat mentality.![](https://nolongerset.com/favicon.png)No Longer SetMike Wolfe![](https://storage.ghost.io/c/eb/d7/ebd732c1-5f03-4f07-b386-5d08557e15c9/content/images/2020/10/brush-wood-4536227_1920.jpg)](https://nolongerset.com/scraps-of-wood-and-code/)

*Image by [Dariusz Sankowski](https://pixabay.com/users/dariuszsankowski-1441456/?utm%5Fsource=link-attribution&utm%5Fmedium=referral&utm%5Fcampaign=image&utm%5Fcontent=1130739) from [Pixabay](https://pixabay.com/?utm%5Fsource=link-attribution&utm%5Fmedium=referral&utm%5Fcampaign=image&utm%5Fcontent=1130739)*