[documentation] Proposal of HandBook and CVS documentation changes!

[Mike Parisi]

I know this post wont be perfect, and I don't mean to insult anyone.  If I do its completely unintentional and due to a statement that was probably a bit skewed.

I have been beating my head over CVS for MONTHS.  Partially because the documentation is scattered and not organized.  Often times you read a document and it mentions allot of specifics (But not all) about CVS.  What you need is missing, for example a major document on CVS contribute does not contain other CVS utilities, while these are located in another section of the site.  This leaves the reader feeling empty and also leaves us not looking elsewhere.  This also bloats pages so that users feel daunted by the tasks required.

I propose a major change in the structure of these sections for many reasons.  The most prominent one is that the information is scattered across 3 separate area's!

http://drupal.org/node/10259
http://drupal.org/node/7765
http://drupal.org/handbook/cvs 

I think that many of these pages are bloated duplicate information and thus are not read!  This is evident in the http://drupal.org/cvs-application/requirements contains the following statement: 

"If you just scrolled down this page to the apply link and didn't read the page, don't expect to get a CVS account. It seems many people are doing just that and submitting poor motivation messages resulting in a high decline rate."

Well this is probably because people can not find the information they need, and the page contains everything from CVS information to Coding Standards information.  I will fix a few problems I have found with the current structure, but this is very complex set of documentation with allot of overlapping information and unclear navigation.

One proposal is that much of the information should (or is) included in the http://drupal.org/handbook/cvs, and removed from the handbook.  Instead a sub page in the handbook that specifically talks about CVS and Coding Standards should be added to the handbook.  That adds a quick over-view of why CVS and Coding Standards and where to find the information needed.  It is important 

Finding the documents is confounded because Druplicons "cvs?" command is unclear at best and does not include all three links above.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.drupal.org/pipermail/documentation/attachments/20090427/2cf1f3d2/attachment.htm>