[drupal-docs] Plan for moving to new handbook (was: Moving Nodes vs. Creating New Nodes)

[bryan kennedy]

Wow, pardon the long response....

On May 8, 2005, at 4:06 AM, puregin wrote:

>
> I'd suggest that we make a plan and make sure that we're
> pretty clear about the usual items: what, who, when, how, where,
> why, etc. before we  leap into action.

Agreed, otherwise the effort is going to be carried out by a select few.

>
>        We need to be aware that there's still some activity around the
> old handbook, and we don't want to pull the rug out from under
> anyone or archive off something that's only half done.

That's exactly why we need a documentation freeze like I suggested a  
while back.  I explain further below.

>
> Plan C:
> ----------

I think a mass copy is not a good idea.  It imports all the cruft and  
problems of the old handbook into the new one and then forces us to  
sift through a big mess of stuff and figure out if we have found all  
the errors/problems.

Instead I think we should develop anew from the architecture we have  
decided upon.  That way we can aggregate information from multiple  
sources of documentation which has been stated as a goal for the new  
handbook.  We only build a page into the new architecture once we  
think it is solid and meets the standards of the new handbook.

Yes the current handbook will stay there static in time for a while  
(implement a freeze on creating/editing the old handbook).  Then once  
we are ready to go live with handbook v2 we start redirecting links  
from "node/14279" to "handbook/about".  I see no reason to keep old  
documentation frozen in time.  I imagine we could create an archived  
copy if we felt it was necessary for posterity's sake.  This task  
should be given to one person who has the ability to edit the URL  
alias interface site wide (or upload a htaccess file) and can take  
place over a short period of time so that nothing will break.

So now we need to figure out how to move forward creating this new  
content as a team.  I think the best way is to agree on some of the  
things you mention below, and then assign sections to interested people

> In any case, we need to figure out a bunch of things.
>
> Could everyone please look at this list and supply some
> answers/idea and/or new questions?
>
>    - what will we copy?
>         - nodes
>         - comments

The new book should have NO comments in it for now.  If someone  
brings up a good point in the comments about the function of drupal,  
then it should be built into the documentation.  Then it should be  
deleted.  The handbook != forums.
>         - book structure
The first level of this has been agreed upon and exists at : http:// 
drupal.org/handbook/v2
Now we need to decide upon the second level of structure.

>   - what contents, attributes, metadata needs to be modified?
>   - how will the copy be make?
>         - the new copy will have to have the same structure as the  
> old.
>            Obviously the new copy's children should point to the new
> copy's
>            parent nodes...  Other structures to preserve?  How will we
>            deal with comments?  Images?

This is another reason why we shouldn't do a mass copy.  It will  
impose the old structure on our new multiple books handbook.

>         - shall we copy all of the books at once, or do a  
> 'handbook' at
> a time?
>    - who will do this?

We should work on one book (in the new handbook) at a time.  Always  
good to start at the top, so let's work on "About Drupal" : http:// 
drupal.org/handbook/drupal

>    - where should we copy this to?
>         - how shall the archived be named, linked to, presented, etc.
>         - how shall the new version be named, presented, etc.
>    - when shall this be done?
>        - what needs to be done first?
>        - what other constraints do we need to consider?
>     - how shall we test our results, to make sure we've done what
>        we wanted to without breaking anything along the way?

I think this will be good to look at but some of these things are for  
the future.  We can't tackle the whole thing at once.

>
>
> On 7 May 2005, at 11:50 PM, bryan kennedy wrote:
>
>
>> On May 5, 2005, at 11:54 PM, puregin wrote:
>>
>>
>>>      I've been thinking about this, and it seems to me that the
>>> thing to do is to make a copy of each node which we want
>>> to move, and then move the original.
>>>
>>
>> Okay, this is what I have started to do with the new "About the
>> handbook" section.  Please take a look and see if this meets up with
>> what you have described.
>>
>> http://drupal.org/handbook/about
>>
>
>      Looks good, Bryan!    The copyright notice should probably
> be updated to read '2005' rather than 2002-2004 (it's a new
> edition, isn't it?)

Fixed.  Thanks I forgot about that.  I made it 2002-2005 since we are  
building off of content that started back in 2002.

>
>      I like the URL aliasing.  Are we going to do this by hand for
> all pages?  Do we have a plan (chapter names, section numbers?)
> for this?

Hmmm....I guess I don't have a specific guideline other than common  
sense.  We should make sure these mirror the book structure.

cheers,
bryan