Minimalism, Technical Writing, and UI Text

“If I had time, I’d write a shorter letter” - Blaise Pascal

Readers who need software documentation are busy. They don’t want to read “everything.” But what do such readers want? It depends on the perspective, also known as the persona. Two major personas in software are:

  • The developer who needs to know if a product might help them.
  • The user who needs to configure a product through a UI.
    • If the UI is so frustrating that they need to “read the docs,” your readers might already be upset.

Frequently, these perspectives come from the same people. Let’s consider both.

As I discussed in Minimum Viable Documentation for Developers, documentation is part of the sales cycle. Readers who evaluate options need to know, quickly, if the product could work for them. They want to see their use cases, and try them out for themselves. Some of the “best” developer experience pages allow the reader to copy/paste commands, so they can see how the product works on their own laptops.

Next comes the UI. Users who run apps on their phones don’t read docs. Users who run UIs for their software apps want to get the job done quickly. If they have to read documentation to decipher a setting, they might not be happy with your UI.

Whatever the use case, the principle is the same. To quote Strunk and White, “Omit needless words.” That can be hard work. But when you keep words to a minimum, you:

  • Focus on essential information
  • Make everything easier to find
  • Avoid details that readers don’t need

I became hyper-focused on minimizing content when I started working on UI text. I’ve talked about UI text at several conferences. The title of my talk is:

UI Text: Simplicity is Difficult

Here’s a link to my slides and YouTube from LinuxConf Australia 2021:

In my talk, I address the following 10 steps to better UI text:

  1. Know your product
  2. “Don’t Make Me Think”
  3. One easy breath
  4. Two thoughts
  5. Minimize need for docs
  6. Know your audience
  7. Know your stakeholders
  8. Start with the easy stuff
  9. Harder stuff: do your homework
  10. Use style guides

If you want to become a minimalist when you craft software documentation, learn UI text.

Better yet, learn it while working with UI designers. They can teach you about the user experience. You can teach them how to be a minimalist with words. Together, you can learn the skills to manage your product, from a user point of view.

Last modified April.04.2024