[documentation] Brainstorming a new documentation method

[add1sun]

On Aug 23, 2007, at 8:46 AM, Victor Kane wrote:

> 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!

Yes, that is the idea - core docs are CVS versioned and the rest of  
the book is left open.  My point was that turning the "open" part of  
the handbook into versioned docs (DocBook/CVS) is not desired since  
it would effectively lock them down to many people and trying to make  
them versioned without using DocBook/CVS would require resources well  
beyond what we currently have.

- Addi

>
> 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/
>
> --
> 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/b316d31e/attachment.htm