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

[Boris Mann]

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:   Boris Mann
 Status:       active

Hi Drapulled -- while some of your suggestions are useful, they are kind
of far-reaching. So far, no one has "stepped up" to actually *do* any of
these things. We keep telling people that contributing to documentation
starts by adding and/or refactoring even a single page (all users have
this permission)....we don't get a lot of takers, so the documentation
doesn't get updated.


This "issue" you've submitted is more of a discussion piece. If you
intend to contribute, please join the documentation mailing list
(http://lists.drupal.org) and introduce yourself. Even better, as
stated, is starting by refactoring a *single page*.


Specific issues with specific pages are great to put in here. Thanks!




Boris Mann



Previous comments:
------------------------------------------------------------------------

Wed, 03 Jan 2007 23:06:52 +0000 : drapulled

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.