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

[Steven Peck]

I strongly disagree with this two levels only part for a technical manual.  Perhaps if we had less content, then yes, but we have a tremendous amount of complex, flexible content.  (Yes, some of it needs to be consolidated, updated or go away but this a first pass effort I am doing, and others need to jump in on individual pages).  There were more top level items before I started moving and consolidating things.  Yet people still couldn't find anything because of the overwelming mass of choices they were presented with.  So, my goal was to try and group similier/related function content and stick to 3-5 levels if posible.  3 better, but not reasonably practical given the breadth of the content in some trees.  Maintaining fewer larger pages is much harder in many ways then what we are doing now, but I am open to examples.  There are many areas where you will only visit once or twice when installing Drupal and it is imporant that all the content be there, right next to each other.

In the case of Settings, right, it does lack style.  It's an old section.  Settings is an area that is very important apart from other considerations in setting up your site.  Settings is in the admin menu, and when you click on it, You have several things to do here. In an ironic twist, the page you reference is one that I did consolidate content onto.  I looked at, admin >> settings, and went down the list in order.  But..... looking at Default front page, it's to long for adding to that page easily.  People complained that finding information was hard, so, we broke things up and gave them descriptive titles.  I am trying to get them in a logical place and order.  Making individual pages pretty is something that lots of people can help out with.  If you can show an example that makes better sense/reading then cool.  Dramatic changes to the entire structure is something fewer can do at the same time to make sure they are not stepping on each others toes.

The writers guide is here: http://drupal.org/about/authoring <http://drupal.org/about/authoring>   I am not at present following it and per this page:  http://drupal.org/node/24566 we're in a similier neighborhood on style.  I am sort of in firefighting mode right now.  Move and organize an entire section as quickly as posible considering that at any given time I could easily be moving pages people are reading or looking for.  
 
Welcome on board, I look forward to seeing you more.
 
Oh, no one mention pages aliases yet.  Please not yet. There are many pages, where we'll never see aliases, and things are in much to much flux to set any new ones.  Probably in February will be time to set some.

________________________________

From: documentation-bounces at drupal.org on behalf of nathandigriz
Sent: Wed 1/11/2006 3:51 AM
To: documentation at drupal.org
Subject: [documentation] the documentation site is too broken and lacks formatting and writing style



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.


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



-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/ms-tnef
Size: 9220 bytes
Desc: not available
Url : http://lists.drupal.org/pipermail/documentation/attachments/20060112/f1b3f723/attachment.bin