[drupal-docs] Docbook ++ question

[Gabor Hojtsy]

> What is the aim of having the Drupal docs in Docbook?
> or
> What are the targets?
> 
> 1. Is it to provide easy to print PDFs?
> 2. Is it to provide easy conversion to HTML, PS, LaTeX, many others?
> 3. Is it to help authoring?
> 4. Is it required to provide documentation in a bundle for offline
>    reading?
> 5. Have I missed some answers? possibly, yes

Some main ideas behind using docbook IMHO:

  - when used as files in CVS, it brings all the power of CVS
    (ie. patches to the documentation, change control, review of
    changes, etc)
  - it is possible to generate multiple output formats, and
    especially it is very publisher friendly (aiming at a
    publishable book :)

> How do the users prefer to have the documentation? What are their
> preferred ways of using the docs, or consulting them?

IMHO the following are key points:

  - searchability
  - navigation
  - shortcuts
  - offline availability

> I have a feeling that using the book module on drupal is a good
> solution, but it lacks features. The tools for maintaining the book 
> hierarchy and TOCs are there. There is revision control present. There
> is a shortage of output formats though.

There are shortage in:

  - easy editing (I personally find it much more comfortable to edit in
    a desktop editor, then in a dumb textarea)
  - change review (ie. diffs, posting these to the docs ML)
  - accepting patches (ie. outside contributions to the manual)
  - professional output formats
  - translation support

> Is the current drupal book module good and comfortable to use to write
> and publish drupal docs?
> please answer this

Not for me (because of the above).

Goba