Paul M. Jones

So I'm late coming to this conversation, but better late than never, right?

Sean Coates asserts that wikis are not for documentation. I quote: "Now, don't get me wrong. I think wikis have a purpose. I even run one for the doc-folk, but IMO, that purpose is NOT documentation." He laments that wiki is not robust, that it's not semantic, and that it's not structured; to solve these issues in a wiki, he says, would be to make it more complex and effectively a lesser form of DocBook.

This stand, in my opinion, addresses the wrong problem. My basic rebuttal would be that PHP userland lacks not merely "robust" documentation, but that it lacks "almost all" documentation. The key here is not merely to improve the state of existing docs, but to get **any** docs to exist in the first place ... and wikis help with this tremendously. They are not perfect, but they are a great start to get some docs out there.

This is a **long** post, so be warned. I plug Text_Wiki and YaWiki multiple times.

I've written about documentation before, many times, on this blog...

• http://paul-m-jones.com/blog/?p=14
• http://paul-m-jones.com/blog/?p=15
• http://paul-m-jones.com/blog/?p=16

... and on PEAR-DOC and PEAR-DEV; here are some thread links,

• http://marc.theaimsgroup.com/?t=108159655600001&r=1&w=2
• http://marc.theaimsgroup.com/?t=108179653300004&r=1&w=2

and here are some highlights from those threads:

Date: April 12, 2004 3:29:46 PM CDT
From:   pmjones@ciaweb.net
Subject: [PEAR-DOC] Re: [PEAR-DEV] Online doc generator
To:   jcastagnetto@yahoo.com
Cc:   pear-doc@lists.php.net

> > 3. Easy to learn the markup to lower barriers to entry (docs
> > are less sexy than code, let's make it easy to get into them
> > ;-)
>
> Huh? What is so difficult about XML?
>

Indeed; what is so difficult about DocBook?  Obviously something
is flawed in the current PEAR documentation system, or we would
have more docs there.


Date: April 12, 2004 3:47:06 PM CDT
From:   pmjones@ciaweb.net
Subject: Re: [PEAR-DOC] Requirements for Documentation System
To:   jmcastagnetto@php.net
Cc:   pear-doc@lists.php.net

> I am still unsure about why we need
> up-to-the-microsecond updated documentation.

For instant feedback and gratification for the documentor.  You
write code, you get to test it right away and tweak it again.
You write docs, you want to see the results right away so you can
keep tweaking; it is rewarding to the writer, and we want to
reward writers.


Date: April 13, 2004 2:36:37 PM CDT
From:   bmansion@mamasam.com
Subject: Re: [PEAR-DOC] Smashing DocBook
To:   mike@php.net, pear-doc@lists.php.net

> Sorry folks, but I really don't get the point on
> smashing DocBook per se.  If you're able to write
> plain HTML you should by no means have problems
> writing docbook XML.  I also doubt that ::^--
> reST ~~_** is that more easier... :-)

.02 of Mike

<sect1 id="mail.stupid.reply">
<title>Reply to stupid mail</title>
<para>That's not the point</para>
</sect1>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
sgml-parent-document:nil
sgml-default-dtd-file:"../../../manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->


Date: April 14, 2004 1:05:34 PM CDT
From:   pmjones@ciaweb.net
Subject: Re: [PEAR-DOC] Doc help requestedd
Cc:   pear-doc@lists.php.net

Composing documentation, in general, is difficult and
not-immediately-rewarding, especially for coders who are not also
technical writers.  I argue that if there is an open, welcoming,
friendly framework already in place then it will be easier for
developers to iteratively build their documentation.  That way
the writers can concentrate on the writing, not on the system.

I bring all this up (1) to introduce some of the arguments I will make later in this post, and (2) to point out that that documentation is important to me; I place as high a value on good code as I do on good docs. My requirements for good docs are that they are written well, for end-users, in an accessible format, to address actual end-user needs. If they're in plain text, so be it; if they're in PDF, so be it.

On further consideration, it might be easier to address Coates' points one-by-one.

There is a recurring idea in the PEAR community that they'll set up a wiki and fix all of the PEARdoc problems.

The problem with PEAR-DOC is not that the docs are not structured properly; it's that the docs are *not there* to begin with (or that there are not enough, and not written well-enough). I contend it is because entry barriers to PEAR-DOC as a DocBook repository are too high, and that the reward-to-effort ratio in writing PEAR-DOC docs in DocBook is far too low.

"Don't worry," they say, "we'll write a Docbook exporter for our wiki markup."

I am of the opinion that this is simply impossible without comprimising either 1) Docbook's robustness or 2) Wiki's simplicity

Not entirely true; a slight bit of added complexity in wiki markup can have a great deal of added value. C.f. the "function" parser in the Text_Wiki package. But certainly DocBook is far more robust than wiki. However...

In (1), I think we phpdoc'ers would agree that docbook is robust. It allows very detailed parsing that allows us to generate things like PDF and CHM. It allows us to parse the document tree and determine which extensions exist, constants in said extensions, functions in said extensions, the prototypes for said functions. Docbook is primarily focused on meta-data, and while visual markup is considered in meta-data markup, docbook prefers to remain output-ignorant. Docbook is _not_ what-you-think-is-what-you-get, as Wikis often claim to be. Docbook is extremely structured, by nature.

... who cares?

Look, I just want somebody to write some docs on their project so I can read them on the web. I'm trying to do it with my projects. My wikis are output-ignorant too; take a look at Text_Wiki and YaWiki for examples. You can write any renderer you like and it'll go to that output format.

Now, I care as much about semantics as much as anyone else (again, see Text_Wiki for an example of the lengths to which I went to preserve semantic implications of markup), but once you convert it to PDF or whatever, all those happy semantics are **gone** -- those formats just don't care. So the combined arguments "DocBook is semantic and structured" and "DocBook converts to non-semantic output" are almost opposed to each other.

I'll get to the "structure" argument in a minute.

In (2), Wikis are known (and consequentially popular) for their simplicity. Anyone who's tried to create a *||Multi|Column|Table||* would agree that they're meant for simple markup only (but often have certain "complicated" functionality). Sure, it would be possible to implement wiki-specific markup for things like and &entities; but for each one, additional wiki syntax would need to be added. Once enough new syntax was added to accomplish similar goals (robust wiki->docbook conversion), you'd have a toolbox that's no simpler than docbook.

What goals, exactly, are we trying to accomplish? I just want to read me some docs about your project so I can figure out what the sam-hill is going on, and where to start.

Wikis are unstructured, by nature.

Indeed; they are as "unstructured" as the web itself, or as Google.

Here's the thing: wiki page relationships **are** structured. It's just that their structure is flat, in a peer-to-peer model. You address each one individually as a peer, not as part of a hierarchy. This can be good or bad, depending on your requirements.

In fact, one nice thing about a flat structure is that you can lay a hierarchical structure on top of it, and replace that layer at will, to make the hierarchy look like anything you want. Again, c.f. YaWiki, where you can implement a navigational hierarchy using the AreaMap page; this hierarchy can be used in your output, or not, as you see fit.

I believe that anyone who REALLY thinks this should be done has never written a <methodsynopsis> block.

Guilty on that count; I've not written many. But take a look again at Text_Wiki and the "function" parser; it has enough stuff there to satisfy most comers, I think.

Now, don't get me wrong. I think wikis have a purpose. I even run one for the doc-folk, but IMO, that purpose is NOT documentation.

Docbook isn't magic; it's just XML. Once you get past the mental block of "this is hard", it really isn't.

Ah, now we get to the heart of the matter. Coates is right; XML is not hard. But:

Organizing and writing documentation in general **is** hard. Having to learn a new system, and build an environment for your documentation, and then compile your documentation, and then troubleshoot your documentation, is a barrier that needs to be lowered. Sweet merciful jebus, we don't compile our PHP code, why should we have to compile our docs?

Wikis lower this barrier dramatically. They allow a quick-and-easy, fast-feedback, high reward-to-effort ratio, iterative approach to collaborative writing. You don't even need to know the markup; you can just toss up some plain text to start and iteratively refine it as you (and others!) see fit.

For examples of what's possible with YaWiki, check out these sites. Are they perfect? No. But as you can see, the docs are there. :-)

• http://phpyawp.com/
• http://solarphp.com/
• http://wiki.ciaweb.net/
• http://nursing.memphis.edu/

Update: Tidied up the blockquotes so they wrap properly.

I went to see the DreamWorks movie Madagascar this weekend. I'd been looking forward to it for some time, if only because I like good computer animation. Unfortunately, the storyline in Madagascar is not that great; while fun for the family, it'll be more-so for the the kids than the adults. (The work put out by Pixar is much better, both technically and story-wise, and it's just as much fun for the parents as the children.)

In fact, there's one point where the zebra, voiced by Chris Rock (read into that what you wish ;-), cries out "Motherf-" and then is cut off by other conversation mid-word. While it's funny because we know Chris Rock, I found it shocking and unexpected to hear that in a kid's movie.

I'm not going to review the movie here (the IMDB link above has a fine one), but I did want to point out that my favorite parts of the film had nothing at all to do with the main characters. For example, there are these four penguins staging a break for Antarctica, and they're a lot of fun; think mobsters crossed with Special Forces. The two British monkeys, one of whom speaks only in sign language, don't get anywhere near enough screen time. The real laugh-out-loud bits come from the half-insane King Julien of the lemurs (voiced by Sacha Baron Cohen) who is by far the funniest character in the picture . Julien doesn't show up until the second half of the movie, but when he's on screen you're laughing the whole time.

In all, I'd say Madagascar is worth the matinee price, but probably more-worth it if you see it with some kids.

It's been a busy weekend playing catchup on bug reports and feature requests. These projects of mine have seen new releases yesterday and today as a result:

* Contact_Vcard_Build 1.1.1 (bugfixes)
* Contact_Vcard_Parse 1.31.0 (bugfixes)
* DB_Table 1.0.1 (bugfixes)
* Savant3 dev 4

The new Savant release bears a little talking-about. I don't like breaking backwards compatibility even in a development release if I can help it, but there was one issue that required an architectural change related to error handling. That is the removal of error-handling resources (e.g., Savant3_Error_pear, et. al.), which is pretty significant if you use it. (Exceptions are a special case; see below for more on that.)

The original purpose of having error-handling resources was so that you could report and test for errors using your own framework-specific calls. While the Savant3 error resources would allow you to plug into those systems, the number-one complaint I got was that Savant3 still returned errors as Savant3_Error objects, which meant that you had to use Savant3 to check for errors, not the framework-specific error checker. That's obviously a problem, as it doesn't meet the original goal of being able to abstract error reporting and testing.

As a result, I have removed the error-handling resource infrastructure. Instead, if you want to use framework-specific error reporting and testing, you should extend Savant3 and override the error() and isError() methods. For example, if you wanted to use PEAR_Error handling, you would do something like this:

include_once 'Savant3.php';
class Savant3_Pear extends Savant3 {

    public method error($code, $info = array(), $level = E_USER_ERROR,
        $trace = true)
    {
        if (! class_exists('PEAR_Error')) {
            include_once 'PEAR.php';
        }
        $err = PEAR::raiseError($code, $code, $info, $level);
        return $err;
    }

    public function isError($obj)
    {
        if (! class_exists('PEAR_Error')) {
            include_once 'PEAR.php';
        }
        return PEAR::isError($obj);
    }
}

The difference between this and the previous (Savant2) error handler resource architecture is that the call to error() will return a PEAR_Error, not a Savant3_Error. In addition, while you can test for errors using the extended isError() method, you can use PEAR::isError() instead because the returned error object is a real PEAR_Error object. This applies to all frameworks that use their own error handling systems (which is, well, almost all frameworks, including Solar, which now bundles Savant3 as its default template system).

Exceptions are a special case; they're native to PHP5, so they have native support in Savant3 now (instead of being an error handler resource). If you want Savant3 to throw exceptions, call setExceptions(true) and it'll throw Savant3_Exception objects when errors occur.

For full change notes, be sure to visit the Savant3 website.

Before I continue, please note that Clay Loveless volunteered the hosting services and has managed the transition in a most professional way (even though he is not a hosting provider, he's a PHP guru). Clay set up the new services, including mailing list (with transition of archives and addresses), email accounts, Subversion repository, database, web with SSL, and PEAR channel server. He runs Killersoft and Pearified; you really should consider contacting him for your next PHP project, as his attention to detail and commitment to high quality service have been obvious throughout the transition process.

And now the cat is out of the bag; everything we gained in the transition is listed above. Point by point, the details are:

* Solar is still at solarphp.com, the API docs are still at solarphp.com/api/, and bug reporting is still at solarphp.com/bugs.php.

* The Subversion repository is now available for browsing and anonymous reading at solarphp.com/svn/. You want to commit patches or add packages? Email me, the benevolent dictator of the Solar system, at pmjones at solarphp dot com -- we'll work something out.

* Clay set up a PEAR channel server based on Davey Shafik's excellent Cerebral Cortex work. Although there are no packages loaded yet, they will end up at solarphp.com/channel.php. Look for more on that later. In the mean time, you can download the latest release at http://solarphp.com/Solar-0.2.0.tgz.

Right now solarphp.com is hosted at TextDrive, which (a) costs money, and (b) is not too flexible. Through the generous good will of Clay Loveless, who runs pearified.com, Solar will soon be hosted on another machine. Among the benefits will be SSL-based access to the Subversion repository, as well an honest-to-Zoroaster PEAR channel, which means we'll be able to do some cooler stuff with installations and usage tracking.

This may entail a bit of confusion over the next few days. We'll be moving the mailing list, so you may see an "unsubscribe" and then a new "subscribe" in your inboxes. Not sure yet if that'll be necessary, but don't be surprised if it shows up. Don't know yet how to export the archives, but if we can save them, we will.

After that's done I'll post another update. The mailing list and Solar website may be flaky during transition, so if you need to contact me, use my "real" address at pmjones-at-mac-dot-com.

(p.s. Yes, PHP Tropics was excellent. I'll write more about that later. :-)

Really, if you're not reading Ryan King on a regular basis, you're missing a lot of good thinking. In this post, he points to work from Clay Shirky (a true visonary and excellent essayist).

Clay's essay is about hierarchical organization versus user-defined relationships. This is one of the differences between Yahoo (who did a "big up front design" on their catalog to tell you where things go so that the stack "makes sense") and Google (who don't organize at all, they let you sift instantly through the stack). I quote:

Browse versus search is a radical increase in the trust we put in link infrastructure, and in the degree of power derived from that link structure. Browse says the people making the ontology, the people doing the categorization, have the responsibility to organize the world in advance. Given this requirement, the views of the catalogers necessarily override the user's needs and the user's view of the world. If you want something that hasn't been categorized in the way you think about it, you're out of luck.

The search paradigm says the reverse. It says nobody gets to tell you in advance what it is you need. Search says that, at the moment that you are looking for it, we will do our best to service it based on this link structure, because we believe we can build a world where we don't need the hierarchy to coexist with the link structure.

A lot of the conversation that's going on now about categorization starts at a second step -- "Since categorization is a good way to organize the world, we should..." But the first step is to ask the critical question: Is categorization a good idea? We can see, from the Yahoo versus Google example, that there are a number of cases where you get significant value out of not categorizing. Even Google adopted DMOZ, the open source version of the Yahoo directory, and later they downgraded its presence on the site, because almost no one was using it. When people were offered search and categorization side-by-side, fewer and fewer people were using categorization to find things.

Read the whole thing.

Tomorrow I'll be going to PHP Tropics as both a vacation and as professional development. Woohoo! :-)

And on a professional note: If I have not responded to your emails to me about Solar, Text_Wiki, Savant, DB_Table, or any of my other projects, please accept my apologies. I've been horribly busy with my MBA classes and "real" (paying) work and family duties, so everything else has had to sit by the wayside for now. After I get back from Cancun I'll be able to respond with my prior speed (such as it was).

For various reasons, I have purchased a new Mac Mini to take the place of my older Cube, originally purchased in late 2000. (Loud scraping noises from the old hard drive were the last warning I needed -- second hard drive I've had to replace lately.)

It's wonderful. I swear to Jebus it's under two inches tall, and just wide enough to take a slot-loading CD/DVD. Built-in Airport and Bluetooth. Just finished putting my databases back in place from backup. Whisper-quiet. Didn't come with OS X 10.4 installed, but they gave me an upgrade DVD; no big deal on the installation, I usually wipe out any new machine anyway and reinstall from scratch.

The only downside was I had to buy a DVI-to-ADC converter to keep using the older Apple LCD Cinema Display.

Solar is a simple object library and application repository for PHP5 under E_STRICT. It takes hints from PEAR and Horde, and bears some superficial resemblance to Ruby on Rails for its MVC application directory structure.

API documentation is becoming voluminous, and is bundled with the package now, along with an example Solar.config.php file.

The change notes for this release are:

* WARNING: This is a public development release, and is not
    yet stable.

* API documentation is now distributed with Solar
    installations; this accounts for 90% or more of the
    package size.  Look in your PEAR docs/ directory for the
    new files.

* Added a Solar.config.php example to documentation.  Look
    for it in your PEAR docs/ directory.

* Added Solar_Template class (is an extended and customized
    Savant3 class).  Savant3 is now distributed in the
    Template/ directory.

* Solar_App:

    * Converted $action_src, $action_var, and
        $action_default to array keys ($action['src'],
        $action['var'], $action['default']).

    * Added a $view property (is a reference to the shared
        object called 'template'; i.e., a Solar_Template
        object).  Sets up the views directory
        (template_path) automatically, and sets up the added
        paths for user-developed themes automatically.

    * Calling view() now returns the output of the named
        named view, not the path to the file for that view.

    * Calling model() now returns a new instance of the
        named model, instead of the path to the file for
        that model.

* Converted Solar_App_Bugs and Solar_App_Bookmarks to use
    the new and different Solar_App features for $action,
    $view, and view().

* Solar_Cache_File:

    * Now uses '.serial' as the filename extension for
        serialized files no matter what

    * No more prefixing of file names

    * Config values are transferred to protected properties
        so they cannot be changed after instantiation

    * Creates the cache directory if it does not already
        exist.

    * Always hashes the cache entry key (prevents directory
        traversals)

* Solar_Cache_Mem renamed to Solar_Cache_Memcache.

* Solar_App_Bookmarks: if you try to QuickMark a URI that
    you already have bookmarked, you are redirected to that
    entry in your bookmarks (instead of it being stored more
    than once).

* Solar_Sql_Driver: now uses lazy connections. it connects
    at exec() time instead of __construct() time.  This puts
    the speed hit of connecting to the database until the
    last possible instant, which means merely instantiating
    an Sql object should not slow you down.

This month's International PHP Magazine has my article on Yawp; woohoo! :-)

Yawp (for PHP4 and non-strict PHP5) is a single PEAR-compliant class that encapsulates a number of other PEAR classes, and ties them all together with a simple configuration file. When you use Yawp as the base of your application, you get...

    * A single easy-to-edit config file
    * Automated authentication processing
    * Automatic creation of common objects:
          o Database abstraction layer
          o Disk cache
          o Composite logger
          o Benchmark timer
          o Variable dumper
    * Safe accessor methods for PATH_INFO, GET, POST, and configuration values

Be sure the visit the Yawp website for full API and user documentation.