DEV Community

loading...

Use Cases As Documentation

Burdette Lamar
Started out teaching English at Embry-Riddle. Graded 10,000 essays. Lesson learned. Became a mathematics teacher. Discovered computing. Never looked back.
・1 min read

Ben, here on dev.to, 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.

Discussion (5)

Collapse
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.

Collapse
loebkes profile image
Ludwig Göbkes

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?

Collapse
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.

Collapse
burdettelamar profile image
Burdette Lamar Author

Always a wise principle.