Just tried Ruby over the past two days. I won't bore you with the reasons I didn't like it, however one thing really struck me about it that I think we (the Python community) can learn from.
Ruby has ... an issue with docs. That is to say, there are almost none. Well, actually, there are some. For example, the "PickAxe" book (google it), and "Why's" Poignant Guide. But there's a disturbing lack of *built-in* docs for Ruby. Now, the situation is getting better. In fact, it's getting better very quickly. Let me explain. IMO, Perl has docs nailed. I learned Perl before coming to Python, and I can tell you that their docs kick butt. I believe the reason why is (besides Larry's excellent and entertaining writing) because of perldoc. Here's how it works: they write special doc directives into their .pl files that the interpreter ignores, but that the perldoc command processes into a manpage for you. This is a *bit* like what pydoc does, only pydoc just regurgitates docstrings, while perldoc formats special directives into headings, code listings, bulleted lists, etc. Now, the *real* magic of perldoc is that it makes writing small self-contained little manpage style docs easy as pie. What this means is that really good doc writers can sit down and quickly produce something that can be readily incorporated into the perl-doc distribution. *That's* the magic. That's why I think they've organically grown such an amazing crop of great docs. Anyone can quickly and easily write docs that the community can then filter to find the best ones. Back to Ruby's docs. Their situation is getting better. This is because they're picking up on Perl's doc success and doing the same sort of thing. Only, I think their solution may be clunkier because it requires a separate program (rdoc) to process the doc directives, and then you actually read the docs with a program called ri (not sure). Regardless of the minute details, it looks like their docs are starting to get better, rapidly. Here's what I think is currently happening with Python (please correct me if I'm wrong): There's the docutils project http://docutils.sourceforge.net/ which, AFAICT, is working on a number of complicated things, one of which is to have a way to allow you to put reStructuredText markup (aka "reST") ( http://docutils.sourceforge.net/rst.html ) into your docstrings (and presumably have the pydoc command understand it). There's more info in PEP 287 http://www.python.org/doc/peps/pep-0287/ . I certainly don't understand all that Docutils is trying to do. All I'm convinced of is, the real magic is in being able to quickly write a .py file containing marked up docstrings and have the pydoc command be able to render it as something that looks like a man page in my terminal window. If it can later also produce html, that's great too. But *that's* the essense, IMO, of what will foster community involvement in making the docs great, as well as allowing folks to more easily document their own modules and contribute integrated docs to all the great modules already available. It looks like we have the tools do this *right now*. We've got the markup (reST), we've got the tools to churn that into a manpage or html (part of docutils?), and we've got the pydoc command. I think the current hangup is that the docutils guys (being smart and ambitious folks) want to get some sort of inter-doc linking thing working so you can refer from one doc page to another (?). I don't think perldoc has (or needs) that feature... maybe we could put that on the "would be nice to have down the road" list, and get a quick common-sense docstring-reST pydoc setup working for us much sooner? I don't know for sure, but my guess is "yes". Eventually, maybe the tutorial, language reference, library ref, etc., could even all make it into this format, with the html versions generated from the .py/docstring/reST sources. That might make it easier for the community to contribute to them (if their respective maintainers are interested in that). Please note, I certainly don't want to step on the doc-sig folks' toes here -- but rather to generate more interest in what they're doing, and to help make Python be even better in an area that I see it struggling. What do you folks think? Yes, I'm trying to make time to look at the docutils code and the pydoc command to see what's involved. Unfortunately, my spare time is vanishingly close to zero right now. Related link: Doc-SIG http://www.python.org/community/sigs/current/doc-sig/ Thanks, ---John -- http://mail.python.org/mailman/listinfo/python-list
