[documentation] [Documentation task] A complete rethink of the docs is needed

[drapulled]

Issue status update for 
http://drupal.org/node/106690
Post a follow up: 
http://drupal.org/project/comments/add/106690

 Project:      Documentation
 Version:      <none>
 Component:    Misc
 Category:     tasks
 Priority:     normal
 Assigned to:  Anonymous
 Reported by:  drapulled
 Updated by:   drapulled
 Status:       active

Before rushing and patching up the docs,  a complete rethink is needed. 


Here are some of the questions that need addressing:


- What are the target audiences? Beginner, Intermediate, Advanced? What
are their needs?


- What overall experience should the docs deliver? Personally, I would
have liked a manual that take me sequentially from the install to
writing my first module, covering everything along the way. Most of my
time with the docs has not been spent reading them but finding them. 
While all the information is somewhere on the site, it is a real pain
finding it.


- How much information should be delivered per page? (avoid information
overload)


- What are the visual queues needed for people to quickly identify the
sort of content they are looking at? Should every page be identified as
a beginner or advanced page? How should pages visually indicate what
topic they related to? What Drupal version does the current doc page
relates to? Use more color or icons in pages?


- Can the documentation handle different page types?...Like one page
(or node) type for HOWTOs, one page type for overview pages, same for
reference pages and so on. It makes sense to group all the HOWTOs
together and all the Overview pages together as well as havinf them
available at their logical places within handbooks. 


My input here and the extent of my contribution is limited by my Drupal
skills. I am new here and my first week loooking for proper
documentation on what is a brilliant CMS has been particularly
unpleasant.




drapulled