[documentation] Brainstorming a new documentation method

[Victor Kane]

Yeah, well, this debate looks interesting, because the Drupal community is
going to have to decide what approach to take towards their documentation: a
free-style approach (what has been done up till now) or a more
industry-standard, versioned, multi-output one.

Or,.... (and I think this is Steven's idea): both!

The free-style approach will continue, but the best of that could be
abstracted into the versioned, industry standard documentation. Then we can
have the best of all possible worlds, and instead of being dependent upon
individuals, we can be dependent upon process!

saludos,

Victor Kane
http://awebfactory.com.ar

On 8/23/07, add1sun <drupal at rocktreesky.com> wrote:
>
>
> On Aug 22, 2007, at 11:32 PM, Victor Kane wrote:
>
>
>
> On 8/22/07, add1sun <drupal at rocktreesky.com> wrote:
> >
> > ...
>
>
>
> -snip-
>
> since it will be in
> > DocBook format and in CVS - not normal handbook pages.  Replicating
> > the entire community-contributed handbook for each version is really
> > not feasible at this time. ...
>
>
> Some of that work can be automated, and that might make it feasible. There
> are many available DocBook editors and tools, also.
>
>
> Well those two sentences are not as related as it may seem.  We will not
> move the normal, community contributed docs to DocBook/CVS, not because of
> automation or whatnot, but because it will *severely* limit the number of
> people who will contribute to documentation.  Right now any user can create
> a page by clicking an Add Child Page link and Docs maintainers can easily
> edit pages from directly in the handbook.  If we suddenly made everyone use
> CVS and DocBook (even only one of those is enough to kill help, but combined
> it is a massive hurdle) for the whole handbook, we will get even fewer
> people to help/contribute than now (and since the number now is crazy teeny,
> tiny we really can't afford that.)  So when I say replicate
> "community-contributed" I mean actually creating/splitting handbook pages in
> the current Drupal book content type way - not DocBook.
>
>
> saludos,
>
> Victor Kane
> http://awebfactory.com.ar
> --
> Pending work: http://drupal.org/project/issues/documentation/
> List archives: http://lists.drupal.org/pipermail/documentation/
>
>
>
> --
> Pending work: http://drupal.org/project/issues/documentation/
> List archives: http://lists.drupal.org/pipermail/documentation/
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.drupal.org/pipermail/documentation/attachments/20070823/af34ba4c/attachment.htm