These days now that I'm fully in charge of building my own product, I often wonder if we place too much emphasis on centralized documentation sites that users have to deliberately seek out and visit vs in-context documentation snippets that show up as closely as possible to where users might actually need them, deeply integrated into the product and user journeys.
Users don't search for documentation for the sake of finding documentation. They search for documentation because they want to know how or if our product can solve a particular problem they have. My hypothesis is that the documentation discoverability problem is really just a symptom of the product discoverability problem, and that centralizing docs in 1 searchable website to make docs "discoverable" is only addressing the symptom, when that effort can be much better spent addressing the root cause by making the product itself more discoverable and deeply integrating useful documentation into it.
> centralizing docs in 1 searchable website to make docs "discoverable" is only addressing the symptom
a searchable docs website is the most important thing for me. having to "discover" an api by stepping through code and comments is a waste of time--only useful when you already know the basics, which requires documentation
Centralized documentation is valuable for several pieces:
* Easily get an overview of the entire API. I may just be scouting the library, so I want to understand what the API looks like.
* Examples as a starting point. How do I use your API?
* Makes your product more discoverable / approachable to potential users.
Think of your users like a funnel - how are they using the library? What are the common reasons you’re losing potential users? What are the common reasons you’re losing existing users? Users are also different so you have to analyze by cohort.
Now can something better be done? Maybe It takes a lot of work and would have to address the above issues and I don’t know if it would necessarily change the need for something centralized.
I read the documentation before downloading anything, to find out if the software will work for my problem. I’m not sure that “in context” helps with that?
That’s what kaseya is doing with their software, basically having contextual assistance for each feature as an “AI Buddy”, where users can choose to listen/learn or just continue using the product, all integrated as one
Users don't search for documentation for the sake of finding documentation. They search for documentation because they want to know how or if our product can solve a particular problem they have. My hypothesis is that the documentation discoverability problem is really just a symptom of the product discoverability problem, and that centralizing docs in 1 searchable website to make docs "discoverable" is only addressing the symptom, when that effort can be much better spent addressing the root cause by making the product itself more discoverable and deeply integrating useful documentation into it.