[documentation] The handbook organization

[Kieran Lal]

On Aug 30, 2006, at 6:43 AM, Charlie Lowe wrote:

> Two thoughts about current weaknesses of the handbooks: rhetorical  
> strategies for the About section and additional linking.

We need to acknowledge that end users expectations have moved from  
reading information to learn about something to an expectation that  
they should entertained with videos to learn about something.

Cheers,
Kieran

>
> * The functionality of the About section over the rest of the  
> handbook. Most of the other sections are documentation for  
> assisting people on how to use and code for Drupal. They serve as  
> reference texts, and must necessarily be organized so that  
> additional references materials can be added and pages updated as  
> necessary.
>
> But the About section is a different breed of cat. It focuses on  
> marketing Drupal to new members and explaining about how the  
> community works, history, etc. It is not primarily software  
> documentation.
>
> This distinction is important because it would benefit from being  
> rewritten to function more as a whole--not as a set of  
> documentation organized as a reference which is the strategy that  
> has been applied to it--to convey a common vision for what Drupal  
> is about and why people should use Drupal. If written effectively,  
> it would not be a place where anyone would easily be able to insert  
> new pages effectively because an overall rhetorical strategy would  
> guide what is included and what not. The current book module patch  
> that has been reviewed on this list would be very useful in this  
> regard because we might want to limit people's ability to add more  
> pages to this section of the handbook.
>
> If one takes these views, it also helps to understand the place for  
> System Requirements. It might fit best in the Installation and  
> Configuration section, but should be linked from the About section.
>
> * Linking between pages. That also raises another problem with the  
> handbooks. So far, the strategy has always been to ask, "Where does  
> this page go?" and the second question that is rarely asked is  
> "What other pages should link to this page?" While we do want pages  
> to go in the primary place readers might look for them, the  
> handbooks rarely take advantage of the fact that they are a very  
> large hypertext. Figuring out secondary locations where users might  
> be looking for a particular page and putting a link there would  
> significantly increase the usability of the handbook. (We could use  
> drupal.org search queries to determine where this might be happening).
>
> There are three ways we might accomplish this
>
> 1) Minor rewrites of existing pages to include linked text within  
> the body of the existing documentation on the page.
>
> 2) Placeholder pages that are titled the same as the primary page  
> and provide a link. So in the About section, there might be a  
> System Requirements page with text and link that says: "See System  
> Requirements in Installation and Configuration."
>
> 3) A list of links at the bottom of pages, something like  
> "Additional Resources" which would contain something like "See  
> System Requirements in Installation and Configuration" but might  
> also include links to relevant forum pages and external links to  
> offsite locations.
>
> ***
>
> Some combination of these methods might be best. When users have  
> expectations that page should be located somewhere else--i.e., they  
> would look in the handbook in that section--method (2) might be  
> best. When a page seems like it might be a useful follow up to  
> another page that a user would be reading, (1) or (3) might be better.
>
> Charlie Lowe
>
>
>
> Steven Peck wrote:
>> The About Drupal was to contain the history, what we are, misc  
>> references to pretty sites any marketing and some general  
>> knowledge stuff that didn't fit anywhere but were common  
>> questions.  One recent idea is that System requirements might be  
>> better there.  Thoughts?  If so, we can move it.  It's easy with  
>> the handy dandy book module :D
> --
> Pending work: http://drupal.org/project/issues/documentation/
> List archives: http://lists.drupal.org/pipermail/documentation/
>