[documentation] [Documentation task] Breaking the existing Drupal
handbook into multiple books
cel4145
drupal-docs at drupal.org
Mon Mar 27 04:46:33 UTC 2006
Issue status update for
http://drupal.org/node/24666
Post a follow up:
http://drupal.org/project/comments/add/24666
Project: Documentation
Version: <none>
Component: Misc
Category: tasks
Priority: normal
Assigned to: Anonymous
Reported by: cel4145
Updated by: cel4145
-Status: active
+Status: fixed
This has been done for a while. Marking fixed.
cel4145
Previous comments:
------------------------------------------------------------------------
Thu, 09 Jun 2005 15:21:09 +0000 : 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
------------------------------------------------------------------------
Thu, 09 Jun 2005 23:00:13 +0000 : 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
------------------------------------------------------------------------
Thu, 09 Jun 2005 23:48:36 +0000 : 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
------------------------------------------------------------------------
Fri, 10 Jun 2005 02:19:20 +0000 : 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.
------------------------------------------------------------------------
Fri, 10 Jun 2005 02:25:10 +0000 : 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
------------------------------------------------------------------------
Fri, 10 Jun 2005 03:29:30 +0000 : 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?
------------------------------------------------------------------------
Fri, 10 Jun 2005 03:58:26 +0000 : 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.
------------------------------------------------------------------------
Fri, 10 Jun 2005 04:46:40 +0000 : 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).
------------------------------------------------------------------------
Fri, 10 Jun 2005 05:49:13 +0000 : 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
------------------------------------------------------------------------
Fri, 10 Jun 2005 13:30:55 +0000 : 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.
------------------------------------------------------------------------
Sun, 12 Jun 2005 00:25:16 +0000 : Amazon
Here is some information on card sorting and cluster analysis.
http://iawiki.net/CardSorting
Contact me if you want the raw data.
Kieran
------------------------------------------------------------------------
Sun, 12 Jun 2005 05:06:56 +0000 : 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.
------------------------------------------------------------------------
Sun, 12 Jun 2005 05:10:23 +0000 : rivena
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.
------------------------------------------------------------------------
Tue, 14 Jun 2005 04:51:59 +0000 : cel4145
I held off on breaking up the handbook for the moment for a few reasons:
* To see if the books page Dries plans to enable will replace the
current "handbook" page. If not, the handbook page should probably be
recreated using page.module with a list of all the books we'll be
creating.
* We need a mechanism for letting users know when they are in one book
about the other books. Could just be a page at the top tier of each
book. The only title I can think of at the moment is "Consult other
handbooks" or "To learn more"
* We'll need to announce to the community about the change at the point
the new books are created.
------------------------------------------------------------------------
Wed, 06 Jul 2005 03:39:27 +0000 : cel4145
As noted in this post [7] to the community now on the drupal.org home
page, the I've broken the text up into multiple books and created a new
handbook page.
Things left to do:
* For the moment, I put the marketing resources in the About Drupal
section. The card sort [8] had them in the installation and upgrading
section (didn't seem to make sense there).
* Do we now have multiple handbooks? Or is there one handbook with
multiple guides or sections? The latter will sort of be confusing when
thinking in terms of collaborative books. Assuming the former, there
will be many places to update to plural throughout the text.
* Lots of reorganizing to do. I've mainly just moved the main areas
into the relevant sections.
[7] http://drupal.org/node/26423
[8] http://www.websort.net/display/?study=drupaldocumentation
------------------------------------------------------------------------
Wed, 06 Jul 2005 07:28:21 +0000 : Bèr Kessels
I added my comments under http://drupal.org/node/26423#comment-45909. in
a nutshell: I posted ideas on how to improve browsability of the books.
IMO that is broken, at the moment.
More information about the documentation
mailing list