Sunday, May 22. 2005
Wikis are not for documentation
Comments
Display comments as
(Linear | Threaded)
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 :-)
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 :-)
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.
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.
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.
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.
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.
Seems the (imo) more important, and more involved bits like methodsysnopsis can be mostly generated from Reflection.
+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..
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..
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.
If used XInclude, and making each file/part/... a standalone xml means can load directly, without having to do any pre-processing.
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.
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.
QUOTE:
I've never been able to get cygwin to make the manual
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);
}
return preg_replace(array('!^/(cygdrive/)?(\w)/!', '@^/home/.+$@'), array('\2:/', strtr(dirname(dirname(__FILE__)), '\', '/')), $path);
}
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
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
Right.
And this is the problem, IMO.
I'll give you the "They are most excellent for creating documentation for web perusal" and "its just quick and easy to create good looking documentation" 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
And this is the problem, IMO.
I'll give you the "They are most excellent for creating documentation for web perusal" and "its just quick and easy to create good looking documentation" 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
translating manuals from opensource projects seems like a foolish waste of time imho anyways.
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.
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
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
There is a point that has not been stressed enough here: Wiki is great for gathering material 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:
(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!
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 my PHP-Nuke Forum - I even say it openly in my welcome message. ;-)
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
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:
(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!
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 my PHP-Nuke Forum - I even say it openly in my welcome message. ;-)
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
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 LyX. 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 Document processing with LyX and SGML .
The PHP-Nuke HOWTO and the GNU/LInux Command-Line Tools Summary HOWTO 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 Document processing with LyX and SGML (just have a look at the thousands of index entries in the Index of the PHP-Nuke HOWTO to understand what I mean...have you even tried entering 5,000 indexterm tags? :-)).
Chris
The PHP-Nuke HOWTO and the GNU/LInux Command-Line Tools Summary HOWTO 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 Document processing with LyX and SGML (just have a look at the thousands of index entries in the Index of the PHP-Nuke HOWTO to understand what I mean...have you even tried entering 5,000 indexterm tags? :-)).
Chris
Pay the bills...
Calendar
|
July '08 | |||||
| Mon | Tue | Wed | Thu | Fri | Sat | Sun |
| 1 | 2 | 3 | 4 | 5 | 6 | |
| 7 | 8 | 9 | 10 | 11 | 12 | 13 |
| 14 | 15 | 16 | 17 | 18 | 19 | 20 |
| 21 | 22 | 23 | 24 | 25 | 26 | 27 |
| 28 | 29 | 30 | 31 | |||
Quicksearch
Syndicate This Blog
My PERSONAL Blog
Note:
The contents of this blog are my own, PERSONAL opinion and do not represent the thoughts or opinions of the people I work with or for. If you have a beef with something I said, take it up with ME. Thanks (-:
The contents of this blog are my own, PERSONAL opinion and do not represent the thoughts or opinions of the people I work with or for. If you have a beef with something I said, take it up with ME. Thanks (-:
Sean Coates writes a compelling case for php docbook over Wiki's for documentation . I happened to agree up until I saw a link in the article's comments for DocBook Wiki which looks to have the best of both worlds. Of course, I am not a big fan of either and instead prefer phpDocumentor run through PHPXref . Of course, different audience entirely between the two.
Tracked: May 22, 18:07
There are severla people who perfer Wiki-Style markup and the Wiki-way to DocBook for writing technical documentation. When the need for documentation arises, they will set up a wiki and let the users create documentation by themselfes. When they note t
Tracked: May 23, 15:21