Make your documentation specific

Programmers grasp the importance of precision when they/we write code.

Then too often it seems they/we forget it when writing documentation.

Somewhat ironically, I’m not going to include many specifics here. I don’t begrudge any individual for being too busy to leave notes or edit them too meticulously. But it’s a pattern I’ve now observed in several places I’ve worked: a ton of relevant information exists in two-person instant messages, months-old emails, or one person’s head (so we hope they remember it) and not in an established location that any person in the group can use as a reference.

The tech community developed its preferences against overdoing documentation and toward lean startups/Agile methodology for good reason. The global flow of paperwork is excessive. Small teams shouldn’t need to maintain complete logs of every action by anyone at anytime for any reason. All things being equal, less documentation is probably better than more.

All the same, writing down important information for reference goes a long way to not wasting the time and energy of new people – and by extension, not wasting the money of the organization.

I actually think my workplace, the Earlham CS Department, has a structure to handle this better than most: a wiki that any employee or student in the program can edit with minimal training. Teaching people the habit of updating the wiki after major project updates helps preserve institutional memory (funny enough, teams of students have a high turnover rate) and helps new people integrate into the system faster.

Minimizing bureaucracy is good. But making concise, specific, actionable, relatively frequent updates to community-accessible notes is also good. Teams can find a balance.

Leave a Comment