Software Documentation Gaps — Deadly Cut 1

Hello! This article is part of a Death by 1000 Cuts series that shines a light on glaring software development industry failures. I'm confident you'll return to 1000 articles someday.

This article is the first in a series of deadly cuts I’ve experienced and my proposed solutions.

Software Documentation Gaps

I use Google to find documentation. Clicking help sometimes gets the job done. Unfortunately, most of the time, feature documentation is garbage.

I tried Apple’s Photos app. First, I searched for Keep Folder Organization documentation when importing pictures. I thought this would help, but I was wrong. I searched for Import and found prospective documentation. I chose Import photos and movies from your camera to my Mac, which was different from what I was trying to do. However, this was the best documentation I could find at that moment. Unfortunately, the article contained little about keeping a folder organized.

So I Googled, found an article on Apple’s discussion forum, and learned this wasn’t the feature I was looking for. I incorrectly presumed it would move files around and put data into folders.

The real purpose is to create albums based on your folder structure.

The worst aspect of this common problem is the fear of presenting problems. I expect a correction saying I’m dumb for not knowing this. This behavior is not productive. Shutting people down doesn’t improve user experiences.

Solutions

• Use native software documentation systems
• Ideally, add context-sensitive help
• Create comprehensive documentation
• Allow documentation feedback
• Regularly test and improve documentation effectiveness