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.

[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

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
"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/

[Mike Parisi]

Going through these documents, I can find allot of "out of scope" information. I think we can trim out this information to make these documents shorter. People don’t want to read long documents, and do not. Please see http://drupal.org/node/446654#comment-1526984 for an example of were I think this is pushing the limits of what is in scope. In fact allot of this information has nothing to do with CVS access at all!

This document maybe moved, but it wont ever be deleted. It needs allot of attention and the hand of a true writer.

It is clear that there is some frustration over the application process for CVS access. That people are not reading it all. Yet bloating the document makes things worse, not better. We need the best of the best of the Doc Team to come in and re-do this. A good writer will say more in less words. I tend to try and write more to cover all aspects of a topic. Thus I tend to bloat a document to include things that maybe obvious to others.

In the end, the person maintaining CVS access will always get bad CVS requests. I feel this is a crucial area of Drupal that requires a person who has a very patient attitude. Getting people to Contrib. is probably one of the most important aspects of the website and community. I will ask that I am not apart of the people who review's these requests because I know I have the patience of a (thinking of some analogy)... Spitting Cobra! A-HA!

Mike


From: Addison Berry
Sent: Monday, April 27, 2009 5:07 PM
To: A list for documentation writers
Subject: Re: [documentation] Proposal of HandBook and CVS documentationchanges!


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/




--------------------------------------------------------------------------------


--
Pending work: http://drupal.org/project/issues/documentation/
List archives: http://lists.drupal.org/pipermail/documentation/

[Stanly Smith]

--- On Mon, 4/27/09, Mike Parisi <***@rochester.rr.com> wrote:


From: Mike Parisi <***@rochester.rr.com>
Subject: Re: [documentation] Proposal of HandBook and CVS documentationchanges!
To: "A list for documentation writers" <***@drupal.org>
Date: Monday, April 27, 2009, 10:02 PM



Going through these documents, I can find allot of "out of scope" information.  I think we can trim out this information to make these documents shorter.  People don’t want to read long documents, and do not.  Please see http://drupal.org/node/446654#comment-1526984 for an example of were I think this is pushing the limits of what is in scope.  In fact allot of this information has nothing to do with CVS access at all!
 
This document maybe moved, but it wont ever be deleted.  It needs allot of attention and the hand of a true writer.
 
It is clear that there is some frustration over the application process for CVS access.  That people are not reading it all.  Yet bloating the document makes things worse, not better.  We need the best of the best of the Doc Team to come in and re-do this.  A good writer will say more in less words.  I tend to try and write more to cover all aspects of a topic.  Thus I tend to bloat a document to include things that maybe obvious to others.
 
In the end, the person maintaining CVS access will always get bad CVS requests.  I feel this is a crucial area of Drupal that requires a person who has a very patient attitude.  Getting people to Contrib. is probably one of the most important aspects of the website and community.  I will ask that I am not apart of the people who review's these requests because I know I have the patience of a (thinking of some analogy)... Spitting Cobra!  A-HA!
 
Mike



From: Addison Berry
Sent: Monday, April 27, 2009 5:07 PM
To: A list for documentation writers
Subject: Re: [documentation] Proposal of HandBook and CVS documentationchanges!

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/

THANKS FROM STANLEY-----


--
/

[Mike Parisi]

Stanly I am not sure if you meant this to be blank, but your message was lost...

As for all of you who are interested, I have gone through almost all of the Documentation Queue, This may mean that some of the Documentation Items you want have been put as "Fixed". I was very careful in picking out posts that seemed to have been fixed through revisions or other means. I worked with fellow members of the Doc Team to assure that the least amount of problems could of occurred, but with over 400 document issues that I reviewed, I may have made a mistake. So please go to Drupal and check your issues, to make sure no mistakes where made. And please activate any Item you think needs attention. I will work hard in the next few weeks to get as much done to prepare for this and other changes to come. In case a mistake was made, your issue will be moved up in the Queue, so its kind of a good thing!

As for this topic, I have opened up a ticket
http://drupal.org/node/446744

There is a large number of related items to this area of the documentation (more then anywhere else). I am going to focus on improving this area as much as I can where and when I'm needed, but as always we need your help, input, feedback and even WILD IDEAS! I think we need to move out of the box on this one!

Mike


From: Stanly Smith
Sent: Friday, May 01, 2009 9:46 AM
To: A list for documentation writers
Subject: Re: [documentation] Proposal of HandBook and CVSdocumentationchanges!




--- On Mon, 4/27/09, Mike Parisi <***@rochester.rr.com> wrote:


From: Mike Parisi <***@rochester.rr.com>
Subject: Re: [documentation] Proposal of HandBook and CVS documentationchanges!
To: "A list for documentation writers" <***@drupal.org>
Date: Monday, April 27, 2009, 10:02 PM


Going through these documents, I can find allot of "out of scope" information. I think we can trim out this information to make these documents shorter. People don’t want to read long documents, and do not. Please see http://drupal.org/node/446654#comment-1526984 for an example of were I think this is pushing the limits of what is in scope. In fact allot of this information has nothing to do with CVS access at all!

This document maybe moved, but it wont ever be deleted. It needs allot of attention and the hand of a true writer.

It is clear that there is some frustration over the application process for CVS access. That people are not reading it all. Yet bloating the document makes things worse, not better. We need the best of the best of the Doc Team to come in and re-do this. A good writer will say more in less words. I tend to try and write more to cover all aspects of a topic. Thus I tend to bloat a document to include things that maybe obvious to others.

In the end, the person maintaining CVS access will always get bad CVS requests. I feel this is a crucial area of Drupal that requires a person who has a very patient attitude. Getting people to Contrib. is probably one of the most important aspects of the website and community. I will ask that I am not apart of the people who review's these requests because I know I have the patience of a (thinking of some analogy)... Spitting Cobra! A-HA!

Mike


From: Addison Berry
Sent: Monday, April 27, 2009 5:07 PM
To: A list for documentation writers
Subject: Re: [documentation] Proposal of HandBook and CVS documentationchanges!


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/


THANKS FROM STANLEY
-----


--
/




--------------------------------------------------------------------------------


--
Pending work: http://drupal.org/project/issues/documentation/
List archives: http://lists.drupal.org/pipermail/documentation/