[documentation] The handbook organization

[Laura Scott]

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) 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/2bd87e49/attachment-0001.htm