Stephen J. Turnbull wrote: > They're not scared by that example. What you need is a paragraph > below it that says > > """ > Do you think the above is all you should need? If so, you're > right. You can stop reading now. If you think you need more, > we've got that, too. Read on (you may need more coffee). > """ +1 Oleg Broytman writes: > > > Better yet (IMHO) would be to split the huge page into "Logging: Simple > > start" and "Logging: Advanced usage (for the brave of of heart)". > > Splitting is OK, but I disagree about the gloss "for the brave of > heart". > > In my experience, if it is a YAGNI, the complexity is nearly > impenetrable. If you *do* need it, it's not at all difficult to > understand what the complexity is for, and it doesn't even look all > that complex because it matches up with the problem you need to solve. > > If the documentation is still a deterrent, that's a problem with the > documentation and it should be improved. AFAICT, making it clear that > exporting all the internal flexibility is for those who need it, while > most users will rarely need it, should be enough. But I'm not a good > test case, since I already am familiar with XEmacs's similar system. I think I'm a pretty good test case -- knew nothing about logging, still don't know much, found documentation comprehensive but unweildy, and would *still* benefit from a more extensive (though still short) beginner's section, with the prominent paragraph stating I now know enough for simple cases. :) Oh, and awesome module, by the way. Thank you. ~Ethan~
RetroSearch is an open source project built by @garambo | Open a GitHub Issue
Search and Browse the WWW like it's 1997 | Search results from DuckDuckGo
HTML:
3.2
| Encoding:
UTF-8
| Version:
0.7.4