[Mono-docs-list] Re: [Mono-list] Monkeyguide

[Miguel de Icaza]

Hello,

> > How did you create the guide? plain HTML or DocBook?
> 
> It's plain HTML, but it should be easy to convert to DocBook.

It is the time of the year for me to advocate sticking to HTML and style
sheets for the moment.

There are two reasons:

	* Maintaining and producing Docbook documents is painful.

	* Free tools that produce Docbook (Like Emacs SGML mode) are
	  just as painful.

	* The output is ugly as hell. 

The first two are important, because you end up focusing on structure
and tags rather than content, and the content is never produced.  The
ramp up time is too big, and by the time you have sorted everything out,
very little is produced.

HTML on the other hand is easy to produce, people can focus on the
content, and *later* a Docbook enthusiast can focus on translating it to
Docbook, but it does not hamper the development of the document.

To this date (after being involved in projects where DocBook has been
used for many years) I have yet to see a single Docbook document which
is remotely nice to see.

The richness of Docbook and the metadata of docbook are interesting
elements, but I think that Google proves very well that you do not need
structure in order to find information effectively.  It can certainly
help, but lacking the tools to use this information effectively (because
they are non-existant really), I suggest -again- to stick to HTML for
now.

Miguel