[drupal-docs] Moving handbook to docs.drupal.org

[Boris Mann]

On 18-Mar-05, at 1:27 AM, Dries Buytaert wrote:

> Second, moving the documentation to docs.drupal.org has tremendous 
> impact.  Just consider the fact that thousands of links will be 
> broken.  Every handbook page referenced from within drupal.org's 
> forums risks being broken.  Not to mention external sites linking to 
> the handbook.  In two words: "404 hell". By reworking the existing 
> handbook, we can preserve node IDs where possible as well as preserve 
> the node's history.

I understand the issues surrounding 404 hell. I don't think we should 
use node IDs in any case -- aliases without hierarchy (e.g. 
descriptive-page-name) should be used. But I digress...

Lots of forum posts contain links. We've already discussed that forums 
are not the place for permanent info. It's a place where people 
consistently ask the same questions...because they can't find the 
answer in the handbook. Don't get me started on versioning issues, 
because the forums end up containing references to OLD information.

> Third, I can see why starting clean feels comfortable.  Right now, 
> making changes to the handbook makes people feel uncomfortable: "Has 
> this page been rewritten recently?" , "Can I remove this page?", "Do I 
> step on some people's toes if I modify this page?", "Would someone be 
> working on this?", ...

Not the problem. Right now, it is "I have no idea where this info is, 
and even I have trouble finding it", "There is no logical organization 
of anything", and "I'm so frustrated with the current state of the 
handbook I could scream".

If there was a really quick way to re-organize/re-arrange the info, we 
*might* be able to do it in place. Unfortunately, that requires some 
major code development -- either web-based or desktop re-arranging of 
page hierarchies that is faster than having to do it manually page by 
page. And something better than "weight" where you hope it ends up in 
the right order.

Would you like to start discussing the versioning problem? I mean, 
right now, Richard Eriksson has been putting 4.6 info into HTML 
comments so that they are in the right place...that is ridiculous!

> Just imagine Drupal core being open to a changing group of 30+ people 
> and not having CVS to track changes (cfr. site maintainers maintaining 
> the handbook).   Without very strict rules and processes, it would go 
> wrong pretty quick.  Every once in a while we could create a new 
> repository and start fresh, but in the end, it doesn't fix the 
> problem.

I agree we need different processes (or rather, just some better 
notification tools). I don't see a way to do that within the current 
handbook. We need ONE fresh start  so we have a base to start from. We 
can agree to disagree on this point.

My view: I don't see a way forward with the current handbook. I suspect 
CivicSpace et al feel the same (which is why they started with a clean 
slate to begin with). We would like to all work together. I believe we 
can get farther faster with ONE clean break.

Here's an alternative that MIGHT work: give us a new root book -- call 
it handbook v2. The doc team can decide how best to organize this, and 
migrate external and local pages into it. It's still starting from 
scratch, but it retains node IDs.

As I said before, I'd actually rather have multiple roots -- one per 
target end user. For instance, Bryght is going to have little interest 
in maintaining the "Installation" section. And users are for the most 
part going to be uninterested in the Contributor's Guide (which should 
be called the Developer's Guide anyway).

Hope that puts  a few more thoughts and ideas on the table. I have 
another meeting today so I won't be able to make the docs call.

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