What to do with disorganized docs

Organizing docs: your choices

I got a question from a startup executive who didn’t know where to put new content. They didn’t (yet) have product documentation. He was worried about disorganized content, and where to publish news of their new features. Here’s my answer:

Interesting question! (And even better, it’s making me think about my past experience.) Time for a blog post, with the following sections:

  • Background story
  • What to do with disorganized docs
  • Information architecture
  • What to do until

Background story

A few years ago, I worked with some “developers” as they made a “build v. buy” recommendation. They realized that they didn’t have the expertise to build, so they evaluated a few companies. For each company, they looked at features, support, etc. But they also looked at docs.

They narrowed their choice to two products. The docs for both were complete. But the docs for the winning product had docs that are:

  • Easy to find from the front page
    • Clear explanations of concepts
    • Short explanations for each concept
    • Content that’s more readable than academic papers
    • Up to date content (search results for the “losing” company frequently referred to old versions)
  • A getting started guide that lets new users see the value, in minutes

What to do with disorganized docs

Back to the question: what do you do with “a bunch of docs in a bunch of places” when you don’t know where to put new features. It’s not realistic to get to “organized” docs quickly.

The developers that I worked with looked only in one place for each company. Many developers wanted to jump to solutions, which is why many docs.example.com pages include “cards” with use cases. But careful developers scan a table of contents. The best docs are organized in an information architecture.

Information architecture

When modern software docs are organized, they typically follow one of two information architectures:

The best software docs that I’ve seen are organized in one of these architectures. They’re easy to find from their docs.example.com front pages.

What to do until

The best person to put all of this advice into practice is a Technical Writer. But even if that person knows your product and domain, implementing these recommendations take time.

Many smaller startups don’t have “standard” software documentation. Setting that up also takes time.

So what does a startup do until they can get a Technical Writer who can make this all happen?

My advice: find the channel that developers trust most. I’ve found that developers hate marketing content. They’ll look at product docs first. If you use blog posts, find authors with technical domain expertise. If you use a support article, make sure it’s kept up to date. If all you have is marketing content, you’d better hope that your potential customer is managed by gullable executives.

Notes

I put “developers” in quotes, as that frequently includes other audiences such as systems administrators and support engineers.

Last modified January.01.0001