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