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.

Comments

boris mann’s picture

boris mann commented

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!

sepeck’s picture

sepeck commented
Status: Active » Closed (fixed)

The installation and configuration guide is being re factored to ONLY be an installation and configuration guide for Drupal core with some basic best practices and site maintenance tossed in. Anything beyond that is open for discussion but so far all anyone says are we have crappy docs but fail completely to be specific. Generally they mean they cannot find answers to specific questions they have, there fore the documentation must be crappy. When I ask for specifics, many disappear.

Please join the docs list and let's discuss this.