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

[Dries Buytaert]

On 17 Mar 2005, at 16:18, Boris Mann wrote:
> Much like we have not been afraid to change code/APIs if it makes
> things better for Drupal code, I believe we need to do the same with
> the Drupal handbook.

The documentation team shouldn't be afraid to reorganize the existing 
handbook but it is not like we (developers) have been throwing away all 
code to start fresh.  While we are not afraid to break existing code, 
we don't start "clean".  Imagine us starting with an empty repository.  
Sure, sometimes a module gets rewritten from scratch but this would be 
equivalent to rewriting a section in the handbook.  Code-wise we use 
incremental improvements and partial rewrites to move things forward.

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.

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?", ...

Starting fresh, on the other hand, takes away these problems. It makes 
you feel like you're on top of things: you know who's been working on 
what sections, there is a sense of ownership (you can change "your" 
pages as you see fit), it is easier to identify work-needing areas, 
etc.   Unfortunately, it is only a temporary advantage. It won't take 
long until people begin to feel uncomfortable making changes.  It is an 
illusion.  :)

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.

--
Dries Buytaert  ::  http://www.buytaert.net/