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...

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

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. :-)

Update: Tidied up the blockquotes so they wrap properly.

Are you stuck with a legacy PHP application? You should buy my book because it gives you a step-by-step guide to improving you codebase, all while keeping it running the whole time.