1. May 7th, 2007

    Patience, Buildr docs coming up

    Right now if you go to the Buildr web page, it redirects you to the RDocs. As Steve Ivy says:

    This reminds me of the bad old days when all Java code just shipped with the JavaDocs and that was “enough”. The API is not the documentation, folks. It’s a useful part of the documentation, but it’s not enough.

    I agree. RDocs are not acceptable documentations.

    RDocs are reference material, information you need after you know what you’re looking for, and just need to quickly find it.

    As part of developing the code, I also wrote a getting started guide for Buildr. It ended up reading like a WS-* spec. Bad. And it fell out of sync with the last set of changes to Buildr. Also bad.

    So I’m rewriting it from scratch. To be readable, usable and friendly.

    Except an official Buildr announcement later this week that will include usable documentation. One you can actually learn from. Hopefully, one you’ll enjoy reading from.

    Printable PDF | Posted by Assaf Filed in Uncategorized 3 Comments »

    1. May 7th, 2007

      monkinetic | Blog Archive » Patience

      [...] Now that’s how it’s supposed too work. [...]

    2. May 8th, 2007

      Mat Schaffer

      Not sure how your writing it, but I think Rake and Rails are decent examples of how RDocs can work as reasonable documentation. Basically give every major class page plenty of example code or files such that someone knows how to use them. Granted nothing beats a good tutorial, but there’s no need to knock RDocs. What’d they ever do to you! :-P

    3. May 8th, 2007

      SteveIvy

      Mat,

      I admit my title (“I hate RDoc”) was somewhat tongue-in-cheek, but I think my point stands, that in the bad-old-days the “docs” most libraries in the Java world shipped with were like Buildr’s current RDocs – no intro (in english), few or no examples, etc.

      I think that part of the problem is that the structured format of inline docs (JavaDoc, RDoc, perldoc, etc) does not lend itself to writing the “human-readable” documentation that really helps users get the heads around the code and into the same space that the developer was in.

      IMO this kind of documentation is best written on a blank white sheet – where the developer can practice getting into the user’s headspace first, then bring the user into their space. “This is what I was thinking and this is how to understand and benefit from it…”

      Anyway, a few more cents’ worth. ;-)

    Your comment, here ⇓