[documentation] Proposal of HandBook and CVS documentation changes!

[Addison Berry]

Yeah, this stuff has been in need of a "do-over" for a while  
generally. I will say though that these *were* more consolidated when  
the Getting Involved book was created. I have reverted the moves that  
have happened since then to re-consolidate them, for the time-being.  
That is, I have moved Drupal and CVS back to the Getting Involved  
guide, and I moved the Start/Maintain a Module back under the  
Contribute Code section. We definitely have some large architectural  
issues in the handbook and we also do not have any clear way to  
"control" it, even if we set it, since different people see things  
being organized in different ways and we have no restrictions on book  
organizational changes at the moment.

I would ask that folks hold off making big location changes in the  
documentation for the time-being, unless it is discussed on the list  
or in an issue in the doc queue first, with broad consensus that it  
"just makes sense." The reason for this is that I will be making a  
really big announcement in the next two weeks about the overall docs  
roadmap and one of the biggest pieces of that will be the IA  
(information architecture) of all Drupal docs. We have an IA person  
who has volunteered to lead the project (and everyone will be  
encouraged to be a part of it). Once we get some preliminary stuff  
taken care of and I can articulate all of this stuff in a meaningful  
way about how we can move forward, I'll be posting to the doc list and  
then making a front page post on Drupal.org.

Mike, thanks for bringing this up, as it is very important and  
something we need to really figure out a long-term solution for, so I  
hope you will keep digging in to this and giving us feedback.

Thanks all :-)
Addi

On Apr 27, 2009, at 4:38 PM, Mike Parisi wrote:

> 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.
>
> --
> Pending work: http://drupal.org/project/issues/documentation/
> List archives: http://lists.drupal.org/pipermail/documentation/

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.drupal.org/pipermail/documentation/attachments/20090427/9db66619/attachment-0001.htm>