On 02Nov2010 03:42, jk <sanjo...@yahoo.com> wrote: | I've been coding in PHP and Java for years, and their documentation is | concise, well structured and easy to scan.
While I agree about Java, at least the core Java docs, and javadoc output in general (_great_ cross referencing!) I have mixed feelings about the PHP docs. Though I suspect that stems from a dislike of the PHP library API in general more than the docs, perhaps. | Others have mentioned this apparently for years (see: | http://stackoverflow.com/questions/4046166/easy-to-navigate-online-python-reference-manual/4070851 | and http://www.russellbeattie.com/blog/python-library-docs-still-suck | and http://xahlee.org/perl-python/xlali_skami_cukta.html). | | Compare for instance the differences in ease of use, and speed of use, | of these: | | http://docs.python.org/library/functions.html#open | http://uk.php.net/manual/en/function.fopen.php | | The former is difficult to find (try searching for 'open' in the | search box and see what you get). I confess I almost never use the search box - as you say the result relevance can be dodgy. However, I do find the docs easy to use and pleasant to read on the whole. My use is as follows: For speed and convenience I have the docs locally stored. I open the front page and then usually both the modules and index in adjacent brwoser tabs. I go to the index if I'm not sure of the module. The strength of the index is that it tends to contain stuff that people thought should be indexed (versus searches, which often have no contextual understanding of the text, so their relevance is weaker). The weakness of the index is that it can be hard to pick the relevant entry. Open-link-in-new-tab is my friend here:-( | It is simply a collection of | paragraphs without strong enough contrast to differentiate the | different parts - parameters, parameter values, return types, | exceptions and related functions. It is slow to read and doesn't allow | easy visual scanning. That is true (the scanning). But by contrast, it does read like prose and lends itself to a visit that gets you a complete feel for the function. [...] | Has anyone else struggled while trying to learn the language? The | whole documentation system seems geared towards people who already | know what they're looking for and is close to useless for beginners. | I'm not the only one who finds google an easier way to find | documentation about python. I certainly don't find the core docs hard to use (with some exceptions; I still don't really understand the urllib stuff for the cases where configuration is needed - weird proxy setups etc). I've only been using Python for a few years and have generally found that language easy to learn and the docs easy to read. I rarely reach for The Google unless I'm seeking examples; the docs could do with a few more of these IMHO. I understand the attraction of the structured layout javadoc yields but find it leads to "drier" documentation. It also works well for Java because it is strongly typed - a great deal of the structure in the docs can come directly from the code because argument counts, names and types are always explicit (or deducable). These are just initial responses. Now to wade the whole thread:-) -- Cameron Simpson <c...@zip.com.au> DoD#743 http://www.cskk.ezoshosting.com/cs/ On the contrary of what you may think, your hacker is fully aware of your company's dress code. He is fully aware of the fact that it doesn't help him to do his job. - Gregory Hosler <gregory.hos...@eno.ericsson.se> -- http://mail.python.org/mailman/listinfo/python-list