DEV Community

Burdette Lamar
Burdette Lamar

Posted on

Use Cases As Documentation

Ben, here on, replied to a post with this: "Can you further describe this use case?"

And that got me thinking....

First, that when I write doc for a project, I should be thinking more about use cases, and less about features.

Users do not want "features," they want solutions. A use case outlines a problem and a solution, while a feature may be a solution in search of a problem.

And second, that I should consider actually organizing the doc around use cases, rather than around features.

In one of my GitHub projects (the largest one), I built a family of "tour pages" (linked together with prev/next navigation). The tour covers the features in the project.

What if, instead, I built a family of "use-case" pages, emphasizing the problem/solution paradigm? Wouldn't the table of contents show users what problems are solved by the project?

I'm going to spend some time exploring this.

Meanwhile, any thoughts you may have will be welcome.

Top comments (5)

patricktingen profile image
Patrick Tingen

Interesting idea. I have a project on GitHub as well and often observer new users of my project while starting to work on it (very informative, I can tell). New users - just like myself - don't read a manual, but instead start using the product.

When encountering a problem, it is early enough to start finding a manual. But even then you don't want to have a set of linked pages enumerating all the features. Instead, you will want to jump to the page that describes the solution to your problem. Having the documentation use-case-based sounds like a good way to facilitate this.

loebkes profile image

There is a talk on YouTube about just in time documentation where the recommendation is to document like a FAQ instead of describing features. So it's more or less the same idea I think. You answer questions a user had like how can I do X?

ben profile image
Ben Halpern

There are definitely strong proponents of this approach. But I'd treat it as part of the toolbox, and it might vary from project to project.

burdettelamar profile image
Burdette Lamar

Always a wise principle.