3 ms·
> Tons and tons of details upfront when I just want to find examples of basic usage. It should have the examples section with common patterns right at the top.
by bmn__ 5y ago
> Tons and tons of details upfront when I just want to find examples of basic usage. It should have the examples section with common patterns right at the top.
This is called a synopsis, and lack of one is the single biggest mistake that documentation authors make. When I look across the landscape of programming languages, I see them rarely.
Perl documentation always has a synopsis because it's a big cultural expectation, and it almost always useful to get the user started, or to jog the memory. Man pages have it, too, but they tend to cram too much useless information instead of restricting to common cases and patterns.
- bccdee 5y agoThe issue is that there are conflicting use cases — "I want to refresh myself on how `re` works" and "tell me what order the arguments for `re.match` go in". I think the second use case is most frequent, so an index and some basic examples should go first, but after that a more in-depth synopsis can be very helpful.
- blakesley 5y agoIsn't it more natural that the summary comes first, before the details?
- bccdee 5y agoI don't think most visits to documentation involve reading the summary; they're either looking for a specific detail (which they can find via the index) or for a common snippet that can be expressed in an example. If I'm using `re` and I check the documentation 20 times over the course of the week, I'll probably read the summary on my first visit, and then on each of the 19 subsequent visits I'll be looking for granular function details or patterns that I can copy. I think it makes sense to put the most frequently-used stuff at the top. The summary will probably be denser and harder to skim than the examples anyway. I suppose it really depends though. What you want is to get a bit of everything before the break, so that the user can see a couple intro sentences, a few examples, the index (ideally in a sidebar), and the beginning of the overview before they even have to scroll.