[bind10-dev] Documentation - inplace vs wiki

[Michal 'vorner' Vaner]

Hello

On Mon, Dec 13, 2010 at 05:18:08PM +0000, Stephen Morris wrote:
> > My preference is to keep in the source tree. But the existing formatting 
> > of our doxygen and python docs are not greatly useful to me. I'd like to 
> > see if you have any examples of ideas of generating design docs and 
> > images.

I don't really know. I saw it used in some project, but I don't remember which
one, I just know it can be done. We would have to read the manual of it. Should
I examine it a bit before the meeting?

By formatting you mean how the page looks like? Or the kind of documentation
(like describes functions and parameters, but not how it is put together)?

KDE uses it a lot AFAIK and we could learn something from there.

> My thought was to use OpenOffice to write the documents, which should mean that everyone can read them.

OpenOffice documents have three problems:

- OpenOffice is huge monster. I don't have it on some of my computers (I could
  install it, but I decided I don't need it), it is even worse with stuff like
  PDAs. PDF or html is easier to read.
- When writing documentation, I usually don't want to care about the formatting
  much. I want the system to figure it out by itself, cross-reference it, etc.
- Showing diffs don't work. One of the strong side of version control system is
  that you can see what changed. We lose that one.

And, both PDF and OpenOffice have one distadvantage: they are targeted for
paper. They have pages and are weak at hyperlinks. The documentation will be
probably read on screen, without need to split it into pages and with full
ability for interactivity.

I know, OOo is probably easier to learn, because most people saw some kind of
WYSIWYG editor before, while some kind of markup needs a look into manual from
time to time. I just believe it pays us back.

If we were not to use doxygen, I could recommend asciidoc. It has nice,
wiki-like syntax, most of the time it looks like simple text file, so it is
suitable to be read like it is and it can generate nice output and formatting,
both to html and latex, which can be compiled, just like doxygen does. I
sometime use it in TODO files and even emails and people don't usually notice (I
don't notice most of the time). It just doesn't have the autoextraction ability
of doxygen.

Have a nice day.

-- 
The cost of living is going up, and the chance of living is going down.

Michal 'vorner' Vaner
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 198 bytes
Desc: not available
URL: <https://lists.isc.org/pipermail/bind10-dev/attachments/20101213/a1c07ed6/attachment.bin>