18 ms·
Personally I really dislike the Python documentation for an average module. Return types seem to never be specified and everything is written too much in a tuto
by hahainternet 11y ago
Personally I really dislike the Python documentation for an average module. Return types seem to never be specified and everything is written too much in a tutorial fashion.
However, you bring up a good point as to the Language Reference / Library Reference. I'm not sure if there's anything remotely comparable for Perl6. I'll get looking into what it would need to add it. Also fwiw Perl6's stdlib is not as bare as 5s.
- tormeh 11y agoWhat style would you want it in if not tutorial? You're in the reference to learn something (possibly again), right? That's a situation tutorial style is well suited for.
- grayclhn 11y agoAny effective tutorial is going to gloss over some, potentially lots, of infrequently used confusing edge cases. That's great sometimes. But when I'm trying to understand the infrequent and confusing edge case, a generic tutorial is the last thing I want. Git's man pages get dumped on a lot, but they're some of the best comprehensive reference documentation I can think of off the top of my head and are definitely not in a tutorial style.
- nocman 11y agoWell, when many programmers look up something in a reference, they are looking for details about the API (functions/modules/variables/etc), not necessarily a tutorial on how to use those things. Examples can be good, but usually you are not expecting a full-fledged tutorial. Reference manuals are usually full of nuts-and-bolts details. Examples I can think of are O'Reilly books that have titles that end with "Reference" verses ones that start with "Learning".