[drupal-docs] XHTML in our documentation - Textile, Markdown, ...

[Vladimir Zlatanov]

> Here's the deal: we need standard markup across all drupal
> documentation. This is essential to creating good stylesheets that
> will output the material properly for various viewing devices (screen,
> print, assistive technology). It doesn't matter whether it's HTML or
> XHTML so long as its consistent.
I agree to a point.

> If we can agree on that, we can move to the next discussion, which is
> "what should our standards be?" We effectively need a styleguide for
> drupal docs, just like there is a code styleguide. 
+1

> Lastly, once the styleguide and conventions have been established, we
> can worry about implementation. As Moshe correctly points out, Textile
> and Markdown produce valid code, a requisite for the stylesheets I
> mentioned above.
Unfortunately styleguide and implementation are intermixed issues. Not
everything can be separated. Having said that, I agree that there is 
a need to start from somewhere and just get down to it and do it.

Dries is right about the professional documentation formats. They are
standard and good to convert to and from. 

We do have different issues we need to tackle.

What is the process centered around?
  a bunch of files versioned in cvs vs online editing and collaboration
  targeting online vs offline documentation
  editorial control/quality vs ease of participation
  ....fill in some more

Ideally all of the above sould coexist and not clash, but
that is not going to happen immediately.

The wikipedia model is a proof that it is possible to have
a successful printed book based on online anarchy *g* but
is it really good for drupal?

Some of my views:
We should model our handbook markup and structures around Docbook.
 * It is designed for books.
 * It should be possible without too much hassle to translate to html,
and if we have xhtml style(as in restricted markup) semantically
compliant with docbook we should be able similarly easy to translate
from html.
 * docbook -> pdf, ps, ... there are existing tools
 * the above translations should enable us to import whole documents
into whatever drupal structures we desire.
 * we should define a xhtml document microformat - it will enable
semantic structuring of documentation, while having easy styling for
different media

How to author?
 * I personally think that online authoring is better long term.
 * but we need to accomodate for uploads and conversion from docbook
 * how do we handle differences and branching? Drupal does have
   revision support, but the revision system doesn't support branching.
   Is it actually required or it could be worked around?
 * with the speed of change in drupal documentation maintenance is going
  to be a process rather than a few static releases

Editorial process
 * It is good to have some central editorial control - it should ensure
   the quality of documentation. 
 * It is good to have an immediate overview of pending changes and user
   comments. This encourages participation, and benefits the users as
   well. Think of the difference for developers when they have access
   to release code only or release + cvs. Not all good ideas and advice
   will end up in the handbook, this shouldn't mean they have to be lost
   associated and easy to reach forums could be good.
 
I'll stop here. I'm just trying to highlight the issues. Drupal 
does have most of the technical infrastructure available. The missing 
bits are doable if there is will. 

What about eating our own dogfood?

Cheers,
Vlado