[documentation] The handbook organization

[Steven Peck]

A block for recent content is certainly do-able.  A block for popular
content should be do-able.


________________________________

	From: documentation-bounces at drupal.org
[mailto:documentation-bounces at drupal.org] On Behalf Of Laura Scott
	Sent: Wednesday, August 30, 2006 11:52 AM
	To: A list for documentation writers
	Subject: Re: [documentation] The handbook organization
	
	
	Ultimately I think one of the biggest barriers is what others
have raised, which is discoverability (findability) of the content.
Having a dynamically-generated hierarchical presentation with a few
hand-coded cross-links is inherently limiting, especially when "web 2.0"
is all about relational linking, cutting across hierarchies. 

	I'd like to propose that we look at taxonomy and how we might
use it to offer ways to cut across the vertical content structures.
Taxonomy is always one of the hardest matters to decide on in site
development in my experience, but done well it can really open up the
content. Getting release tags on various handbook pages was a step.

	What about a next step? Can we get a little creative with
taxonomy/categories and some more custom views pages that highlight not
just section headings but most recent additions and most popular pages
in that "section"?

	What would be the approach that could really open things up for
us?

	Laura


	On Aug 30, 2006, at 12:12 AM, Steven Peck wrote:


		Greetings all. 

		There is a post in the distant past that explains the
concepts of how and why the handbooks are ordered the way they are.
Printed out I believe Gunner Langmark said they were a thousand pages.
So for those new to the list, let's just bring folks up to speed with
memories rather then digging through the archive.

		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

		The installation and configuration guide is not actually
meant as the beginners guide to Drupal.  IT can be if you start at the
beginning and click next.  You will progress through requirements,
installation, general configuration to core modules then contrib
modules.  Tossing in the Troubleshooting FAQ for the common issue's and
updating.  This section was meant as a reference and a resource.

		The customization and theming was meant as the bits and
pieces that others had contributed that you could use to make a site
your own.  It was not my original idea but someone else's that I merely
organized into logical divisions.  It to is a resource.

		The developers handbook has always been a fairly organic
thing.  The first pass organization was to try and organize it so that
it was in a logical context with other related items.  It has been tuned
on a regular basis and some of the older content has been edited and
consolidated over the past several months.

		So.  What's missing.  The same thing that has always
been missing.  Tutorials.  Site-recipes was an attempt to get people a
place to put things.  Bits and pieces or complete how to's.  We still
need tutorials.  We still need a beginners manual.  I always thought of
a beginners manual as a sequential series of steps with links to more
expanded content in the other books as needed.  To help train people how
to find information.  A lot of people that we get have little to no idea
how to research so we have to help them.  That's why I answer with a
series of links to the relevant documentation so often in the forums.  I
am not saying rtm, I am showing How to find the information so they can
ask better questions next time.  Some of these folks are obvious part
time guys (power users or soon to be power users) and by teaching them
the process they can use any IT / Internet resource more effectively.

		Now I remember several of us being told by several
people (rather forcefully) that we didn't understand anything and how
they were going to do it better and they were going to show everyone and
setup this site with all this documentation for new people.  It's been
eight months now and I still don't see it so whatever efforts they made
are lost.  So I will say again what I said then.  If someone writes it,
we will find a place for it.  If you have pictures, we can load them up.
In the beginning it would reside in the Installation and configuration
handbook but as it gained content (with the magic of Drupal book module)
we can easily add another book and have it reside there.  This will be
of benefit to everyone.

		I had hoped to have time to finish this series
(http://www.blkmtn.org/book/drupal <http://www.blkmtn.org/book/drupal> )
and go through an entire WINK presentation but frankly my workload has
been far more insane this year then predicted.  On the bright side, our
new director is tired of us working 2-3 weekends a month as well as
evening hours all the time and is bringing on new people to reduce the
workload.  (whew).  On the other plus side my wife is 5 months pregnant
with our second, but this means a little less time with Drupal this
winter (She likes that I do this, it's a hobby that keeps me home)

		So.... It's been eight months since I re-did the
handbook.... Anyone tried 4.8/5.0?  Thoughts, suggestions?  It's a bit
different.  I have some rather radical thoughts but really want to hear
other people's suggestions first. 

		Steven 

		--
		Pending work:
http://drupal.org/project/issues/documentation/
		List archives:
http://lists.drupal.org/pipermail/documentation/


-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.drupal.org/pipermail/documentation/attachments/20060830/8be85b2b/attachment.htm