[drupal-docs] [task] Breaking the existing Drupal handbook into
multiple books
rivena
drupal-docs at drupal.org
Sun Jun 12 05:10:26 UTC 2005
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: rivena
Status: active
One thing to note is, with the 5 books above, there is no one
'contributing' section, so documentation, with regards to the handbook,
falls naturally under 'about the handbook'. Looking at it now, the
content division seems much clearer than I originally thought.
I am still all for a block on every handbook page that links people to
how to contribute to the handbook and what the guidelines are. :)
Anisa.
rivena
Previous comments:
------------------------------------------------------------------------
June 10, 2005 - 00: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 10, 2005 - 08: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 10, 2005 - 08: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 10, 2005 - 11: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 10, 2005 - 11: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
------------------------------------------------------------------------
June 10, 2005 - 12:29 : cel4145
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?
------------------------------------------------------------------------
June 10, 2005 - 12:58 : rivena
The information Charlie asked for would certainly be useful. We can
definitely, and should, cross reference pages to lead a person to the
page they want in fewer clicks. People have different senses for how
things should be organized. We can organize the handbook according to
the card sort, and then have links to related pages for the people who
don't fall into the majority there.
Djun's suggestion is useful, but perhaps a snippet is best placed in
context... for example, block snippets under blocks, book
modifications under the book module. I still wonder about the
feasibility of perhaps tagging all these pages with 'code hacks' and
then we could easily create listings of all pages which have code
modifications.
There was a previous discussion on this on the Wiki... Not sure what
happened to it. :(
Anisa.
------------------------------------------------------------------------
June 10, 2005 - 13:46 : cel4145
"Djun's suggestion is useful, but perhaps a snippet is best placed in
context... for example, block snippets under blocks, book modifications
under the book module. I still wonder about the feasibility of perhaps
tagging all these pages with 'code hacks' and then we could easily
create listings of all pages which have code modifications."
+1 for tagging.
So we don't get off track, first we have to reorganize the books. So
let's say that we will definitely be planning on how to tag the
handbook once we get the handbook pages reorganized. If someone wants
to begin collecting ideas now, then I'd suggest creating a new issue
specifically about tagging the handbook(s). But let's not plan on
making any decisions about tagging the handbook until we are done (or
almost done) restructuring because what and how we tag will in part be
dependent on how we structure the handbook(s).
Second, so we also stay on track, let's focus on general structures
now: how many books, what will be the title/focus, and roughly, what
will go in them (what do we need to move now). No need to figure out
exactly where every single page will go yet. I think we can do this now
without statistical data on the clustering (that' s me getting us off
track :-) I also personally think that is too hard a task/taking on
too much at once because we'll get caught up in the specifics rather
than deciding on the big picture.
Then once we have the general structure, we can create new issues for
each new book and decide more specifically what goes in them and how
they are to be restructured (if necessary).
------------------------------------------------------------------------
June 10, 2005 - 14:49 : Amazon
Mark Leicester has volunteered to do tagging. I saw you put him in
charge of tagging and let him run wild.
"I think we can do this now without statistical data on the clustering
(that' s me getting us off track :-)"
Here is R http://www.r-project.org/
Here is the source file:
http://demo.civicspacelabs.org/home/files/drupaldocumentation.txt
Here are some clustering packages for R
http://www.google.com/search?hl=en&lr=&client=safari&rls=en&q=site%3Ar-project.org+clustering+algorithm&btnG=Search
Of course if you don't think that we should use statistical methods to
organize the handbook, then I suppose we could just you know, wing it
;-)
I feel strongly that we settled the handbook titles and the number of
handbooks a few months back. Let's end that discussion and move to
organizing each book.
Kieran
------------------------------------------------------------------------
June 10, 2005 - 22:30 : cel4145
"Of course if you don't think that we should use statistical methods to
organize the handbook, then I suppose we could just you know, wing it
;-)
I feel strongly that we settled the handbook titles and the number of
handbooks a few months back. Let's end that discussion and move to
organizing each book."
Definitely additional statistics would be useful for organizing the
individual books (does someone want to take this on and create a new
issue?). As for what was decided, Bryan K had created five books which
are essentially the same as above except that for the Drupal
documentation part he had "About the handbook." Was this what was
decided? If so, I'll separate the handbook this weekend. I'll leave
the translator's guide in the Developing section for the moment (based
upon the graph). We can let the translators decide where they want it
since they are the target audience after all.
------------------------------------------------------------------------
June 12, 2005 - 09:25 : Amazon
Here is some information on card sorting and cluster analysis.
http://iawiki.net/CardSorting
Contact me if you want the raw data.
Kieran
------------------------------------------------------------------------
June 12, 2005 - 14:06 : rivena
This is what was discussed earlier:
http://dev.bryght.com/t/wiki/HandbookVersionTwo
As Kieran says, if possible, it's better not to redo the whole
discussion over again.
To summarize, these are the handbooks created:
* About Drupal
* Installation and upgrading
* Configuration and customization
* Developing for Drupal
* About the Handbook
Anisa.
More information about the drupal-docs
mailing list