Wikis **Are** For Documentation

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: [email protected] Subject: [PEAR-DOC] Re: [PEAR-DEV] Online doc generator To: [email protected] Cc: [email protected] > > 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: [email protected] Subject: Re: [PEAR-DOC] Requirements for Documentation System To: [email protected] Cc: [email protected] > 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: [email protected] Subject: Re: [PEAR-DOC] Smashing DocBook To: [email protected], [email protected] > 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: [email protected] Subject: Re: [PEAR-DOC] Doc help requestedd Cc: [email protected] 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 your codebase, all while keeping it running the whole time.
Share This!Share on Google+Share on FacebookTweet about this on TwitterShare on RedditShare on LinkedIn

10 thoughts on “Wikis **Are** For Documentation

  1. Does this post mean its time that I bring up my feature requests on the yawiki list again? 😉

  2. Short response…

    You make some good points. I definitely agree with you on the ‘PEAR needs good docs, PERIOD, even if they’re not docbook’ point.

    I don’t, however agree with the “docs don’t need to be semantic and structured” point. Imagine reading a newspaper that used a random font and text size in each article? Imagine if the pages were numbered non-sequencially (but no worries: there’s an index at the back)? We can agree to disagree on this, if you like, but I strongly assert that the best documentation (and I truly believe that phpdoc is some of the best open source documentation available) IS semantic, robust and structured. There’s a value to changing formats.

    Livedocs (once working properly with all php.net doc projects) will solve the accessibility problems. As it stands, I can change phpdoc (and as long as I don’t add entities (including files), or change the master manual file), I can see the changes, rendered, instantly in Livedocs. If I _DO_ change entities/manual master, it’s a matter of seconds (sometimes minutes) to re-`build.sh`, and not hours (as it stands with the DSSSL build).

    My only other point: my biggest fear of a wiki for PEAR packages is not that people will use it as a base for their docs, but that it will _become_ the docs due to laziness and negligence (they’ll never get ported to the “official” format). The docs, while somewhat useful, will remain mediocre. If you’re going to do something: do it well. MHO.

    (oh.. and too bad you didn’t trackback me (rather, your trackbacks don’t seem to work properly).. I’d have seen this sooner (-: )

    S

  3. “Imagine reading a newspaper that used a random font and text size in each article?”

    Wikis dont allow all that much different markup to really make this a valid comparision.

  4. one more thing: i agree that you want structure for API docs, but end user docs dont need structure quite as badly.

  5. Lukas — re: API vs. end user docs. I absolutely agree, and made that the point of my own blog entry (referenced in an earlier comment). I feel that this is what Paul is getting at as well. The API docs *should* and *will* remain structured, as they will be auto-generated from phpdoc blocks. But end user documentation is the part that has the highest barrier to entry, as this is where DocBook comes into play.

    And when it comes down to it, end user docs often need even less structure than the API docs — some simple headings, some lists, some paragraphs.

    Sean has made some fine points — inter-page linking is harder to maintain on docs that are distributed. But I feel that Text_Wiki actually has the ability to handle that already, and could likely export documents in such a way that these issues would be overcome.

  6. All — agreed that API docs require a great deal of structure. However, that is completely automated via processing of doc-blocks in the code itself, and mostly useless except as a reference when you already know the class moderately well. End-user docs are my target here.

    As far as inter-page linking, Text_Wiki handles it very nicely. In fact, on the Solar wiki pages, I’ve set it up so that interwikis use double-colons, not just single-colors. With that one change, every time you type ClassName::methodName(), it converts to a link to the ClassName area and the methodName() page. Same for ClassName::$property. Makes it really easy to link pages.

  7. […] Paul M. Jones has a great blog post entitled Wikis **Are** For Documentation. He says: This stand [that wikis are insufficient for documentation -ed.], 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. […]

Leave a Reply

Your email address will not be published. Required fields are marked *