[drupal-docs] [task] Breaking the existing Drupal handbook into multiple books

[cel4145]

Issue status update for http://drupal.org/node/24666

 Project:      Documentation
 Version:      <none>
 Component:    Misc
 Category:     tasks
 Priority:     normal
 Assigned to:  Anonymous
 Reported by:  cel4145
 Updated by:   cel4145
 Status:       active

I see the card sorting as a good general guide. But to take full
advantage of it, we need some additional information because


1) we don't know much about our sample set (although I would guess that
it is heavily weighted toward developers and accomplished
administrators).


2) we don't know whether, for example 49% of users liked one grouping
and 51% another. If we were more aware of the grouping choices and felt
that where 49% of users chose to group it probably was a better choice
for the main audience we imagine, we would know to override the
majority.


Also, knowing if say 2/3 of users liked grouping A and 1/3 liked
grouping B would suggest that we need to make sure we include a page
(if it is a section being grouped) or a link (for only one page) in
grouping B to point users with that expectation to the right
book/section/page.


Meanwhile, I think that Djun's suggestions of Cookbook and Hacks would
fit in those groupings. Seems like it's easy enough to have a Cookbook
section and a Hacks section using the four book structure. Is there an
advantage to having these outside of those books?


As for the fifth book, I thought we might want to keep documentation
writing/documentation project teams out of the development section
because people associate developing with code.  Does this make sense?




cel4145



Previous comments:
------------------------------------------------------------------------

June 9, 2005 - 10:21 : cel4145

Once the V2 handbook pages are removed, we can begin separating the
existing handbook into the smaller books. Following is a tentative
outline for the five different books which tries to layout where to
include the various sections of the existing handbook. There may have
been a another outline suggested previously. If so, please post it so
that we can compare. 


Please also review and revise.  If anyone would like to volunteer to do
the moving, please accept assignment for this issue.



* About Drupal [1]
* Installation and upgrading Drupal [2]

* Installation section of Administrator's guide 


* Configuring and customizing Drupal  [3]

* Administrator's guide (except for Installation)
* Translator's guide 


* Developing for Drupal [4]

* Contributor's guide
* Module developer's guide 
* Theme developer's guide


* Drupal Documentation ("Documentation writer's guide" and "About the
handbook")

*Notes*



*  Since each of these is a different book, I've included "Drupal" in
the title.
* I've changed the last handbook from "About the handbook" to "Drupal
Documentation" (is there a better title?)With each Drupal handbook, we
would then include a page called "About the handbook" pointing to the
relevant information in "Documentation" handbook.
* Seems like "Translator's guide" fits best in Configuration and
customization, but I'm not sure. 

[1] http://drupal.org/handbook/drupal
[2] http://drupal.org/handbook/install
[3] http://drupal.org/handbook/config
[4] http://drupal.org/handbook/devel




------------------------------------------------------------------------

June 9, 2005 - 18:00 : puregin

Looks good, Charlie.


Comments:



* "Installation and upgrading..." should probably read "Installing or
upgrading..." to be internally parallel and consistent with the other
titles.
* I like the placement of the Translator's guide with "Configuring
Drupal"
* How about "The Drupal documentation project" as a title for the last
section?
* I've been thinking that there should probably be a couple of other
books:

* a "Hacks" book organizing the little snippets, one-liners, tips,
tricks, etc.  (Inspired by the O'Reilly Hacks [5] series)
* a "Cookbook", covering topics such as "how to set up a monthly online
newsletter", "how to use taxonomies to simplify navigation", "how to
build an e-commerce site with Drupal", etc.  (Inspired by the O'Reilly
Cookbooks [6] series.)



P.S.  You can try out the new 'export DocBook XML' and 'export OPML'
features for book module - OPML may be helpful in playing around with
arrangements of the book structure in an outlining tool; while
exporting to DocBook may help with bulk edits.  


I am working on import for these formats, so hopefully moving pages
around won't be too onerous when the time comes.


Djun


[5] http://hacks.oreilly.com
[6] http://cookbooks.oreilly.com




------------------------------------------------------------------------

June 9, 2005 - 18:48 : Amazon

According to the WebSort usability study most documentation users
expected language translation to be in the "developing for Drupal"
handbook.


The results are here:
http://www.websort.net/display/?study=drupaldocumentation


It looks like cluster analysis suggests people were statisfied with
four books.  You'll have to interpret the handbooks yourself but it's
pretty obvious what they were.


Cheers,
Kieran




------------------------------------------------------------------------

June 9, 2005 - 21:19 : cel4145

Any way to see some sort of statistics on the cluster analysis or some
sort of weight for user preferences? I really don't know how the
clusters are generated, but I'm concerned since the graph doesn't
indicate where user might have been closely split.




------------------------------------------------------------------------

June 9, 2005 - 21:25 : Amazon

I can get you raw data and I can get you the dendogram.   I can probably
get you a description of the clustering algorithm, but I don't think
I'll be able to give detailed statistics.


I am sure there is closet analyst our there somewhere dying to throw
the raw data into R.  Volunteers?


Kieran