[documentation] The handbook organization

Wed Aug 30 18:11:14 UTC 2006

On Aug 30, 2006, at 1:37 PM, Kieran Lal wrote:

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

makes sense. i guess a tutorial/recipe section of screencasts on how to 
do everything possible with drupal could be a great resource. although 
maintaining that and keeping it up to date might be tough...

>
> 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/
>>
>
> --
> Pending work: http://drupal.org/project/issues/documentation/
> List archives: http://lists.drupal.org/pipermail/documentation/
>
>
\
jochen|at|jochenhartmann.com
jochen.hartmann|at|gmail.com
http://jochenhartmann.com | http://quilted.org
\\