[documentation] the documentation site is too broken and lacks formatting and writing style

[nathandigriz]

Hello,

I guess my first post should not be a complaint but it is also what 
prompted me to join. I think the drupal.org  handbook is too broken p. 
It does not make for helpful reading and lacks writing style. In other 
words the information is there but no one is goingto read it because 
there are too many obstacles. An example is the settings and 
configurationsection . The text lacks headers and content seperation. 
There is also a breaking up up of information because although the 
configuration is on a single page in Drupal, the instructions are broken 
up into 9 lead pages and dozens of child pages. This is unnecessary and 
creates more confusion while putting a stop to the short term attention 
span of the user.

A Better Style:
The handbook should actually read like a book and not a deep linked 
website. Nothing should go more than 2 levels deep and lead pages should 
have read more links after a paragraph if more detailed information must 
be given for a section. an example below...

Name: this is where you set the name displayed for your site.

E-mail address: A valid e-mail address for this website, used by the 
auto-mailer during registration, new password requests, notifications, 
etc. You can set this to a real email address that people can reply to 
or to something generic no-reply at example.com 
<mailto:no-reply at example.com> that is outbound only. The email server 
that your site uses is set in the php.ini file and not by Drupal.

Slogan: The slogan of this website. Some themes display a slogan when 
available. It will also by displayed in the title bar of your sites 
visitor web browser.

Mission: Your site's mission statement or focus.

Footer: This text will be displayed at the bottom of each page. Useful 
for adding a copyright notice to your pages.

Anonymous user: Users who interact with your site without being logged 
in are labeled as "Anonymous" by default. Drupal gives you the option to 
change this to something different (e.g. "Anonymous coward"). The name 
you give anonymous users is used by Drupal when creating bylines for 
posts which typically reads something like, "Posted by Anonymous on 
January 1, 2006".

Thsi section should read like this...

Name: this is where you set the name displayed for your site.

E-mail address:
A valid e-mail address for this website, used by the auto-mailer during 
registration, new password requests, notifications, etc. You can set 
this to a real email address that people can reply to or to something 
generic no-reply at example.com <mailto:no-reply at example.com> that is 
outbound only. The email server that your site uses is set in the 
php.ini file and not by Drupal.

Slogan:
The slogan of this website. Some themes display a slogan when available. 
It will also by displayed in the title bar of your sites visitor web 
browser.

Mission:
Your site's mission statement or focus.

Footer:
This text will be displayed at the bottom of each page. Useful for 
adding a copyright notice to your pages.

Anonymous user:
Users who interact with your site without being logged in are labeled as 
"Anonymous" by default. Drupal gives you the option to change this to 
something different (e.g. "Anonymous coward"). The name you give 
anonymous users is used by Drupal when creating bylines for posts which 
typically reads something like, "Posted by Anonymous on January 1, 2006".

default front page:
This section should not have a seperate page as it does now. It is not 
called for under the context of doing a " basic configuration. There 
should be a short explaination here with a read more link to another 
handbook page if more details of how to best accomplish more than the 
basics are needed.
read more...

In conclusion:
Furthermore I think that there whould be a handbook page that shows the 
right writing format and style to be used in the handbook. There does 
not seem to be anything wrong with the handbook information. There is 
lots of it and it is useful. The problem is in how it is being 
delivered. To repeat in a different manner: There are too many short 
paragraphs on different pages that give no information on the task at 
hand. They are only serving to deep link the handbook.