[drupal-docs] Regarding the drupal help documentation

[Charlie Lowe]

Dan Robinson wrote:
 > Below please find a thread regarding the effort to improve the Drupal
 > help system.  Please excuse my lack of knowledge, stupidity and refusal
 > to do thorough research before jumping into this matter - but I wanted
 > to *do* something and now that I have I feel like we can have a
 > conversation about it.  I'm copying a thread from over in CSL land - for
 > reasons that I think are unfortunate, but obvious - comments welcome -
 >



If I can offer a suggestion about the block help text. I would not say 
that the text is too long, but that the style used makes it too long. 
For good web texts and good documentation, it's good to make it 
"scannable" in recognition of the fact that people use help 
documentation as a reference; they don't necessarily read everything, 
but are looking for something. And it tends to make the documentation 
more readable anyway online (where readibility is an issue with 
electronic texts).

So to improve on the readability/usability, try breaking it into a 
couple of sections. You could use list elements to organize like things. 
  Try grouping by task with the idea that the user will be using one 
page at a time. Those things on the admin/block page, explain together. 
Those settings for "configure" for a block also together. So you might 
have a heading for "modifying and creating blocks" which would include 
information about how to add one and how to then configure it.

For example, notice how I broke up

http://dev.bryght.com/t/wiki/BookHelp

Now this is not the best documentation that I've ever put together (I 
still feel like it needs something in terms of formatting), but I feel 
like the organization and formatting made a significant difference. 
Compare the online version above to how it would look without any 
formatting below. Without that formatting,

Charlie

The Drupal handbook on drupal.org was been created using the Drupal 
wiki-like collaborative book The collaborative book feature is well 
suited for creating structured multi-page hypertexts such as a site 
resource guides, manual, Frequently Asked Questions (FAQs) and the like, 
allowing you to have chapters, sections, etc. Unlike a wiki, as each new 
page is added to a collaborative book, it is placed into a menu 
structure much like a table of contents. Book pages have navigation 
elements for moving through the text, such as the previous, up, and next 
elements visible at the bottom of each book page.
Other collaborative book features

Use the printer-friendly version link visible at the bottom of any book 
page to generate a plain text, printer friendly display of that page and 
all of its child (sub) pages.

Use the outline tab when viewing any node type--blog, story, poll, 
forum, etc.--to add it into the collaborative book.

Drupal provides three levels of permissions to control who can 
administer books, create book pages, and edit book pages. Visit 
administer » access control (admin/access) to set the permissions for 
your book.

Go to administer » content » books (admin/node/book) and select your 
book title from the sidebar navigation menu. From there you can change 
the title or weight (easily reordering the book), or edit and/or delete 
a book page. At the bottom of the list of books in the sidebar 
navigation, you'll find a link for orphan pages--book pages which have 
lost their parent (i.e., the parent page has been deleted)--so that you 
can reclaim them.

A sidebar menu block which acts a table of contents for users to 
navigate a collaborative book. Site administrators can enable the book 
navigation block on the administer » blocks page (admin/block).

To create book pages, go to create content » book page (node/add/book). 
Then enter a Title for your book page.Select the Parent page to place 
the book page into the appropriate place in your book structure. If 
creating a new book for which there are no pages yet, choose 
<top-level>. You must have administrator privileges to create a new 
book. (Note: you can always edit an existing page and use the Parent 
setting to reposition a book page within the text).As with any other 
node, enter the text to display within the Body. If editing revising a 
book page, you can use the log message to leave a note about the 
revisions. The log message will only be visible to book administrators. 
By default, book pages with the same parent or ordered alphabetically by 
title and given the default weight of 0. Use the weight to override the 
defaults. Lighter numbers (negative numbers) will rise to the top of the 
order; heavier numbers (positive numbers) will fall to the bottom of the 
order.