[documentation] The handbook organization

[Steven Peck]

The barrier to writing tutorials is less then screen casts.  However, if
there are tutorials, they can be converted into screen casts by others.
Even if there are video's, a written tutorial that accompanied it would
be valuable.

Either way... Whichever people choose to contrib is fine.  As long as
something beyond conversation is produced.  

-sp

> -----Original Message-----
> From: documentation-bounces at drupal.org 
> [mailto:documentation-bounces at drupal.org] On Behalf Of jochen.hartmann
> Sent: Wednesday, August 30, 2006 11:11 AM
> To: A list for documentation writers
> Subject: Re: [documentation] The handbook organization
> 
> 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
> \\
> 
> --
> Pending work: http://drupal.org/project/issues/documentation/
> List archives: http://lists.drupal.org/pipermail/documentation/
> 
>