[drupal-docs] On docbooks

[Steven Peck]

Arg, to busy to track my emails lists... this is so cool.  I am going to see if I can get a public test install of it as well to play with.

________________________________

From: drupal-docs-bounces at drupal.org on behalf of Djun Kim
Sent: Thu 4/21/2005 4:34 PM
To: drupal-docs at drupal.org
Subject: Re: [drupal-docs] On docbooks



Quoting Boris Mann <boris at bryght.com>:

>
> On 21-Apr-05, at 9:14 AM, Anisa wrote:
>
>> OK, so, I probably wouldn't even be able to make a hello world
>> module, so I do not know the technical issues involved, but if ya'll
>> are so enamored with DocBooks, what about something like this:
>>
>> http://doc-book.sourceforge.net/homepage/
>>
>> A demo of what it looks like is here:
>>
>> http://www.soft.inima.al/book/
>>
>> Pros, cons, this stuff sucks?  The features seem pretty nice, but
>> I've been fooled by pretty feature lists before (cpg nuke!).  I'd
>> install it, but you  know...  shared hosting and all that.  ^.^
>
> Oooh. Nice find, Anisa. Meets our wiki requirement for easy editing
> by anyone as well as DocBook requirements. This might be a really
> good target to have up at docs.drupal.org...
>

   Agreed!  I looked at this briefly a couple of days ago, and it
seemed pretty nice.  I had reservations about whether contributors
would feel comfortable editing DocBook, but it appears that
this has been addressed.  If Boris (who is rightly insistent on
simplicity for the user) likes it, I think we have a winner.
I should confess at this point, that I've not spent a lot of
time working with the system - there could be little problems
which could drive us crazy, or perhaps show-stoppers - a little
more real time spent testing would reassure me.

  Now for some questions - do we use this as-is, say on
docs.drupal.org?  Or try to adapt to work within Drupal?

If this is to be a separate repository for our new handbook,
how will this be positioned relative to the existing handbook
on Drupal.org?  Do we close the existing handbook, migrate the
content into DocBook, and bring it up in DocBookWiki, giving
a starting point from which to create the new handbook (HB2 -
the handbook, reloaded :)

Or should we put the new top-level sections in place and
try to construct the new book ab initio?

What happens to the old version?  Should we put links to the
new document into each node, and then remove add/edit
permissions?

How will review/change management happen?

Where shall we go to start putting our pet peeves and nits into
a style guide? (While glancing over the PDF version of the
old handbook [1] I noticed the following gem as a description
of a sample module: 'This module will help you get laid' :)


>
>>  I view the process of building handbook 2 in this manner:
>>  1. Decide the general organization of content.
>> http://dev.bryght.com/t/wiki/HandbookVersionTwo
>>  2. Establish serious, detailed, style guides, as Djun Kim
>> suggested.  http://drupal.org/node/15289
>>  3. Establish a work flow.  For example, wiki > handbook > print format.
>>  4. Review old documentation and rewrite, and reorganize based on
>> new guidelines.
>>  5. Voila, beauty.
>
> +1 on this as well. I think we're pretty close to consensus on the
> top level sections.

  +1 from me too - Voila, indeed :)


> --
> Boris Mann
> http://www.bryght.com


-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/ms-tnef
Size: 6526 bytes
Desc: not available
Url : http://drupal3.drupal.org/pipermail/documentation/attachments/20050422/e53881df/attachment.bin