Jeff Bailey
Written by Jeff Bailey

Learning resources, opinions, and facts about technology.

Software Documentation Gaps – Deadly Cut 1

Reading Time: 3.2 minutes
Listen to this post

Hello, this article is part of my Death by 1000 Cuts series. I intend to shine a light on big software industry problems, and I have complete confidence I will have written 1000 articles someday.

Keep Folder Organization feature on macOS explained and clarified.

This article is the first in a series of deadly cuts that I have experienced and a proposed solution.

Software Documentation Gaps

My go-to way of getting documentation is a Google search. It would be ideal to rely on clicking help and getting the answers we’re looking for every time. Unfortunately, most of the time, the thing we are trying to do is not documented.

I’ve been trying out Apple’s Photos app. First, I searched the documentation to find what Keep Folder Organization means when importing pictures with the keyword Keep Folder Organization. I thought this would help me move on with my life with a better understanding.

Unfortunately, using the documentation did not immediately pay dividends. I then searched for Import and landed at what looked like the right place.

I chose Import photos and movies from your camera to Mac, which was not what I was trying to do. This was the best documentation I could find at that moment. Unfortunately, the article did not mention anything about keeping a folder organized.

So I went to Google and found an article on Apple’s discussion forum, and this feature was not what I thought it was at all. I thought the feature would move files around and put data into folders or something of that nature. The real purpose is to create albums based on your folder structure.

The worst part of this common problem is that people are afraid to present their problems. I expect someone to correct me and say I’m dumb for not knowing how to do this. This behavior is not productive. Shutting people down does not help improve user experiences for anyone.

Software Documentation Gaps


  • Use whatever godforsaken help system the software framework has available
  • Add context-sensitive help alongside controls to save people time
  • Do whatever it takes to avoid making people dig through incomplete documentation
  • Take a community-centric approach. Allow people to make comments that relate to the control in question
  • If laziness sets in, then at least provide a link to a Google search page