[documentation] The handbook organization

[Kieran Lal]

On Aug 30, 2006, at 7:38 AM, jochen.hartmann wrote:

> I think something like a structured FAQ section would also be  
> really good. I find that the forums are usually where i go but it's  
> hard sometimes to have to read 10+ different posts on some issue  
> that I need an answer too especially if certain items are pretty  
> straight forward... Maybe the FAQ could cover the drupal 'terrain' - 
> > core, themes, modules, users, forms, etc?

Again we need to adapt to users changing expectations.

Users want video summaries.

They want to use search to find stuff, because that's proving to be  
more effective than categorization schemes that are constantly out of  
date.  It's our job to give Steven feedback on why searching for top  
terms is not giving the results we would recommend.

Kieran

>
>
> On Aug 30, 2006, at 9:56 AM, Kieran Lal wrote:
>
>>
>> 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/
>>>
>>
>> --
>> Pending work: http://drupal.org/project/issues/documentation/
>> List archives: http://lists.drupal.org/pipermail/documentation/
>>
>>
> Jochen Hartmann
> jochen at quilted.org
> http://quilted.org
>
> --
> Pending work: http://drupal.org/project/issues/documentation/
> List archives: http://lists.drupal.org/pipermail/documentation/
>