[drupal-docs] Regarding the drupal help documentation

[Dan Robinson]

> 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. 

ok - agreed that it needs to be formatted - it seems that others 
disagree about the length.

> 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.
>
>
>
>