[documentation] The handbook organization

[jochen.hartmann]

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?


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