[documentation] The handbook organization

[Charlie Lowe]

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

* 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