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.
Top comments (4)
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.
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?
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.
Always a wise principle.