Yesterday, I posted a rant about Docbook, Wikis, and how they're fundamentally different, on the PHP documentation list.
Since the audience of that list is fairly limited, and its participants generally of the same mind, concerning Docbook's virtues, I thought I'd re-post it here for all to see.
I'd like to know your opinion. Especially if you're proficient in Docbook, but disagree with me. ---- There is a recurring idea in the PEAR community that they'll set up a wiki and fix all of the PEARdoc problems. "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
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.
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 <classname> 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. Wikis are unstructured, by nature.
I believe that anyone who REALLY thinks this should be done has never written a <methodsynopsis> block.
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.
</rant>
Helgi Þormar
2005 May 22 11:15
Just give them web UI and some wacky editor like feature with flashy buttons and they'll shut up I guess :-)
And maybe a preview button to see the result.
Should be enough for those kids.
I remember when I came up with that wiki idea sometime ago, it was intended to be something similar to what Trac has, or well just a way to have some quick way to setup some page for a PEAR package if people didn't have any resources to setup one, but suddently people started talking about docs and what not, so I just made my self fade from the "project", funny how things evolve sometime :-)
Clay Loveless
2005 May 22 11:59
Amen! I've felt the same way -- what's the big deal about docbook markup being hard? It's just XML. Pull up a reference list of tags, and use them.
For a group of people proficient in HTML 4, XHTML 1, CSS 1/2, PHP 4/5, Smarty/Flexy/IT/Pick-Your-Flavor-Template and Wiki markup, plus Javascript, all the bitching about DocBook just seems ... bitchy.
Quit complaining and start writing documentation like it's supposed to be written.
A good possibility for a compromise:
http://doc-book.sourceforge.net/homepage/
Theoretically, this will let Wiki fans continue doing what they're doing, but magically produce DocBook. Perhaps a good learning tool for basic DocBook tags.
S
2005 May 22 12:44
Heh. This software partially inspired my rant (-;
See [url=http://marc.theaimsgroup.com/?l=phpdoc&m=111667331509733&w=2]this post[/url].
S
Harry Fuecks
2005 May 22 15:48
This is a subject that's had me pondering for a while now.
Think it's not entirely fair to compare a wiki to docbook directly, the former being an application (implemented in many different ways). Sounds like syntax has become the focus of frustrations.
Strikes me the core needs for documentation and PEAR are; shallow learning curve, ease of use and less work in keeping docs up to date. On the surface a wiki might tackle some of this but could quickly seem is degenerating into a mess no one maintains. Perhaps more specific solutions would help, rather than turning to wikis as a magic bullet?
Given that PEAR developers only need a subset of the php docbook tags, which itself is a subset of docbook, wouldn't it be possible to implement a simple syntax geared only for generating a specific type of document, which can be transformed to docbook? Something wiki-ish with a very small vocab, focused on meta data, avoiding formatting vocab and very hard to "break" (unlike docbook), with a disclaimer "need more, learn docbook". That should solve the issue for most people writing docs for their PEAR packages I'd guess.
Otherwise, slightly diverging from the topic, this might be interesting: http://wiki.splitbrain.org/wiki:discussion:integrationwithapidoctool.
Ren
2005 May 22 19:11
Do documentors of PEAR really need to know that much DocBook?
Seems the (imo) more important, and more involved bits like methodsysnopsis can be mostly generated from Reflection.
Alan Knowles
2005 May 22 19:21
+100 here, wiki's always stuck me as a way to work around the fact there used to be no WYSIWYG HTML editors for web pages.
Now that is pretty much solved, they seem a bit redundant..
The ideal solution is probably Conglomerate or writing some kind of docbook WYSIWYG editor in JS/Mozilla... - It just seems like no-one has had the enthusiasm yet to solve it fully..
Ren
2005 May 22 20:18
One of the problems with a DHTML WYSIWYG editor is the large size of docbook sources, as most(?) use system entities for splitting content.
If used XInclude, and making each file/part/... a standalone xml means can load directly, without having to do any pre-processing.
Greg Beaver
2005 May 22 21:38
I've never understood the problem people have with docbook in peardoc.
Actually, that's not true - before I wrote the phpDocumentor->docbook converter, I thought making people use docbook just sucked. Now, the "it's too hard" argument doesn't hold water.
The documentation I maintain for pear.php.net on packages I've written is generated in one of two ways:
1) spit out the basics from phpDocumentor and hand-tweak
2) cut and paste from existing pages
The only resource I've needed to get things going is a unix box (docbook just doesn't work on windows - I've never been able to get cygwin to make the manual, no matter what I try) and this webpage:
http://www.docbook.org/tdg/en/html/docbook.html
With those two items, it's just plain easy. Docbook has a few quirks, but for english-speakers it's not that far off from intuitive if you have that manual to look at.
Ren
2005 May 23 06:39
[quote]I've never been able to get cygwin to make the manual[/quote]
Why do you need cygwin for docbook?
Get the native tools from libxml2 (xsltproc & xmllint) and should be all you need for using docbook XML & XSL.
I dont even use cygwin for building the PHP manual, but rather the MingGW developer tool kit
http://prdownloads.sourceforge.net/mingw/msysDTK-1.0.1.exe?download
Seem far less painful, thou one of the strip_cygdrive function in phpdoc/scripts/file-entities.php need altering
[code]
function strip_cygdrive($path){
return preg_replace(array('!^/(cygdrive/)?(\w)/!', '@^/home/.+$@'), array('\2:/', strtr(dirname(dirname(__FILE__)), '\\', '/')), $path);
}
[/code]
Davey Shafik
2005 May 23 08:52
I disagree whole-heartedly here.
Wikis are not for creating DocBook. They are most excellent for creating documentation for web perusal.
I would never have written the docs I have for Cerebral Cortex without using YaWiki, its just quick and easy to create good looking documentation.
I also think that you could use Wiki markup to generate *some* level of DocBook, but it should only be a starting point, similar to the phpDocumentor DocBook output.
I think that at the end of the day, most people care more about how their docs look visually, than whether they carry enough metadata or not.
- Davey
S
2005 May 23 11:14
Right.
And this is the problem, IMO.
I'll give you the [i]"They are most excellent for creating documentation for web perusal"[/i] and [i]"its just quick and easy to create good looking documentation"[/i] arguments. Unfortunately, I think you've managed to sum up documentation short-sightedness, right there.
For CRTX, I'm sure that's all you care about: good looking docs that can be browsed on the web. And since it's _your_ project, that's fine. phpdoc (and I hope, someday, peardoc) doesn't suffer from this myopia, though.
It's important to be able to distribute the manual to 100+ mirrors, translate it into dozens of languages, export into intelligent offline-viewable formats, etc.
As far as I'm concerned, docbook vs. wiki is analogous to well-designed code vs. hacked-together code. The latter "works", but it's not portable, and makes assumptions that may not always be true. It is, however, more accessible (to the writer).
S
chris
2005 May 24 04:34
Well, I think the debate should be enlarge to the kind of documentation you produce and who is writing it in order to choose the right tool.
First, let us agree on what is technical documentation and technical people.
For brief, technical documentation is code documentation and technical people are programmers. Everything else is non technical doc and non technical people.
So, a non technical documentation is for example end user documentation of a software and non technical people are whoever except programmer.
IMHO,
* technical doc written by technical people should be done in DocBook. This is the tool which allows the maximum flexibility/power and which programmers can handle. Talking about WYSIWIG is nearly non sense (however, having the HTML render in "real time" is quite a good solution)
* non technical doc written by non technical people should be done through wiki because this kind of people can not understand DocBook. Moreover, DocBook is for technical doc (as it is said in the standard purpose)
* technical doc written by non technical people is non sense because the writter will not understand very well what he is writing about
* non technical doc written by technical people is also a non sense becase they will not write documentation understandable by non technical people
In fact, like everything else, the problem is not the tool, it is why a tool and who is going to use it.
Regards,
chris
Lukas
2005 May 24 07:36
translating manuals from opensource projects seems like a foolish waste of time imho anyways.
Lukas
2005 May 24 07:40
I should probably add that a partner company had a working export to flat file openoffice off of yawiki for an older version of Text_Wiki. It produced great results. We just had to manually go in and fix page breaks and click on all tables once to get them properly formatted (probably doable via a macro). The output included images, image index as well as table of contents. We could then export this to PDF as needed.
Chris Karakas
2005 May 24 08:16
There is a point that has not been stressed enough here: Wiki is great for [i]gathering material[/i] to be later used in a DocBook documentation.
Wiki cannot replace DocBook. Wiki should not attempt to. But we should not ban Wiki, just because we want to use DocBook. My message is:
[b](Mis)use Wiki to gather all the feedback / insights / wisdom / suggestions / solutions / contributions of your users. Then go and cut and paste all that wealth of information in your favourite DocBook framework, enter whatever DocBook tags you need to tag it adequately for your purposes - and be happy![/b]
BTW, you can (mis)use a Forum the same way: people will come to ask you a question, you will write the answer - and this way you have gained yet another piece of text to be used in your documentation / book / treatise on the subject. That's how I plan to (mis)use [url=http://www.karakas-online.de/forum/phpnuke.html]my PHP-Nuke Forum[/url] - I even say it openly in [url=http://www.karakas-online.de/forum/viewtopic.php?t=2]my welcome message[/url]. ;-)
If you have a look at the Forum's titles, you will see that they could come from a HOWTO - that's where the line between a Forum, a Wiki and a HOWTO becomes blurred. IMHO the first two are "information gathering tools" for the third.
Without the Wiki / Forum, you would never have had access to such a wealth of interaction. And that's what you need - interaction to make your documentation more complete / useful / correct.
So the message for all documentation people is: don't use Wiki, misuse it! :-)
Chris
Chris Karakas
2005 May 24 08:25
As for DocBook's lack of a WYSIWY(Think / Mean / Deserve / Whatever) editor, I was faced with this problem 5 years ago. I decided to go with [url=http://www.lyx.org]LyX[/url]. I developed my own framework based on LyX: I write in LyX, then export to SGML DocBook, tweak the SGML a bit with some scripts (a bit too hard for the moment, I admit... ;-)) to correct some errors and insert some features / tags I need, then use a scripted procedure to get HTML, PDF, PS, TXT and even RTF form it. The whole process is described in great detail in [url=http://www.karakas-online.de/mySGML/]Document processing with LyX and SGML[/url] .
The [url=http://www.karakas-online.de/EN-Book/]PHP-Nuke HOWTO[/url] and the [url=http://www.karakas-online.de/gnu-linux-tools-summary/]GNU/LInux Command-Line Tools Summary HOWTO[/url] are written in this way. There is no way you could have produced the DocBook markup of these documents "by hand", just using a simple XML editor, as some seem to have suggested here. You have to use an (at least semi-)automated framework like the one described in [url=http://www.karakas-online.de/mySGML/]Document processing with LyX and SGML[/url] (just have a look at the thousands of index entries in the [url=http://www.karakas-online.de/EN-Book/i20165.html]Index of the PHP-Nuke HOWTO[/url] to understand what I mean...have you even tried entering 5,000 indexterm tags? :-)).
Chris