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 find 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’ve been trying out Apple’s Photos app. First, I searched for Keep Folder Organization documentation when importing pictures. I thought this would help me, but I was wrong. I then 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.

Software Documentation Deadly Cut 1 - Apple Photos Import

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.

Software Documentation Deadly Cut 1 - Gaps

Solutions

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

Other Deadly Cuts