Create First Steps Handbook

Created this issue and assigned to myself to give a venue for discussion of the 'First Steps Handbook'.

The idea is this. The drupal documentation exists. Sure there is always room for improvement, but all the essentials are here. However two outstanding issues prevent people from finding what they need, as they need.

A) There are some many aspects of drupal that you can't explain it the same way to any two 'types' of user.

B) There is no built in doc-only search

Senpai's thrown the gauntlet on B here: http://drupal.org/node/113589

This is my take on A. I want to create a handbook that is user type specific. The main role of this book will be to designate a 'path' through drupal docs for various types of users.

For example, top level page will be something like:

Click here is you are looking at drupal from a design perspective.
Click here is you are looking at drupal from a php/mysql developers perspective.
Click here is you are looking at drupal from a business person's perspective.

Each of these would lead to a series of pages that are relatively version independent. A designer would first want to know about the phptemplate engine, and theming. A developer would want to know about module development. A vanilla admin would need to know the basics of taxonomy.

Each 'path' would eventually lead through the basics of all the docs - with the goal of weaning the user off the path and onto the doc itself, however, each would do it in a different order, with some different wording to help a 'type' of user 'get' drupal.

So what I'd like, before I start this is feedback. Is this useful, needed, a waste of my time, welcome?

Background:

From my 'application' for the team - http://drupal.org/node/114038:

Webchick, Senpai, and I had a IRC conversation about starting a top level book that was as version independent as possible, but referenced existing doc as a path through doc dependent on profession. Kind of a 'Choose your own Adventure' through documentation.

Webchick's follow up:

The folks in the #drupal-dojo channel have identified the biggest problem with Drupal's documentation not the lack of it, or the fact that it's poorly written, but the fact that it's difficult to find. The idea is to have a collection of starting points for various target audiences that aggregate appropriate links to elsewhere in the handbook. I think this is an excellent idea, and might even be able to take over the existing /handbooks link at some point if it works well. In the meantime though, it can't hurt

Below is the conversation that led to all this, with irrelevant information or other conversations snipped out. I took a good deal of editorial liberty cutting, so if anyone feels that I didn't get all that they were saying chime in:

i think we most def need to figure out a better way to centralize all the scattered ideas and communications - i know we're all thinking about it...

gusaus: I dunno. From my perspective we already have that centralization: the handbook.
i wish there was a way that mediawiki could easily integrate with 'drupal' wiki

The documentation would suck a lot less. :D

webchick, It's true that we already hav the Handbooks. My biggest fear with this ne Dojo progect, and the resulting onslaught of info, is that the Handbook Pages are going to become overly-heavy for newbs to grasp
but unless those efforts ultimately end up back in the handbook, it doesn't benefit the widest swath of people iti could.

Senpai: so does it make sense to make a new handbook (or seciton or whatever) for newbie developers? and one for newbie themers..?
I am all about restructuring things so it's more logical and easy for people.

we're not 'locked' into the current structure.. the handbook is an incremental work in progress. ;)
It used to be one huge ass book, so this is an improvement. ;)

The task list is good - if we keep up on it.
but asking the instructor to a) prepare a lesson, b) teach it, and then c) document it in the handbook is too much. so the responsibility has to fall to some other person/s

webchick: agreed - that and the 'students' would get more benefit from writing the doc anyway.
Yep.
There is seriously nothing that helps you understand material better than trying to explain it tomsomeone. :)

Seems like we want to add a handbook to drupal.org maybe... The docs are an intruction book, and a Dojo-esque book that is lesson by lesson write ups heavily crosslinked - but even as I write that I think of upkeep, etc, and cringe
sam, no! Let's not crosslink!
Bad!
I can create a book for you right now if you want. :)
Very bad!
though I think you can too.
Senpai: Ok, why?
hm? crosslinking bad?
Too much upkeep, just like you said
The only thing worse than having no info is having wrong info
crosslinking is the opposite of upkeep... it's "wanna learn more about CVS? there's a whole thing about it right here: X"

webchick: nope -Thats what I had in mind.
A handbook that was SEQUENTIAL that went through drupal from a students persepective - adding some order to the current handbook by referncing it in a step-by-step fashion
There should be as little duplication as possible, imo... so if there's already a part of the handbook that talks about topic X, then re-work that X page so that it's understandable and link to it from your thing.
samtresler: yeah, wicked. i love it.

exactly... this just solve the "Where do I start" problem every noob hits
sam, I hated that phase....
* webchick had a very bizarre noob phase :P
I razed three drupal installs when I first started
Burned them to the ground

Well - I'm still hitting it and I've been at this for a year and a half - The docs
are very well written, and you can't find what you need to save your life
webchick had SoC, no?
samtresler: yeah...
The problem is not the docs's lack-of-info

I need to think on this and examine the existing doc some more
samtresler: so i'm curious how you're thinking of approaching the more 'contextual' step-by-step method.
mainly because there are a plethora of audiences:
webchick: Me too!

1. I'm a complete newbie ... I don't even know HTML. I want a basic blog without any frills.

2. I'm coming from Joomla!/Typo3/Plone/X . I want to know how to do X task I'm familiar with in Drupal.

remember Choose Your Own Adventure Books
I think it needs to be that
3. I'm a master PHP hacker, but know nothing about Drupal. How do I make modules and extend Drupal's functionality?
(turn to page 34)

haha indeed. ;)
no really
But seriously though.
there are at least 10 completely distinct "starting points" I could think of off the top of my head.
4. I'm a business person/manager/X, and trying to evaluate if Drupal is right for me.
5. I want to build "blah" site. How can I do it in Drupal?
That's my point of the choose your own adventure. The work is in the linking - the first page says I want to learn drupal from x perspective
6. I'm a photoshop whiz. How do I translate my masterpieces into Drupal?
No webchick, there's only one starting point. For the newb who has just downloaded 5.0, and run the easy-as-cake installer, they have only one thing on their mind. "How Do I Do x.."
7. I've been using Drupal for awhile as a basic user, and now want to take it to the next level...
and has those 5+ options. And each one takes you to an overview of Drupal from that perspective - and those are the only 5-10 pages in the book - the rest is a list of the order in which you should absorb the doc.
Senpai: spend some time reading the support forums...

there are MANY many different starting points.
kay
Designers start with CSS includes and phptemplate engine
It's actually mind boggling.
and it makes writing documentation very very hard.
* josh_k (n=joshk@75.111.49.109) has joined #drupal-dojo
Which is why sam's idea of having a "jump off page" for each audience member is such an awesome idea.
So existing pages are not re-written.
just aggregated in a way that makes sense to target audience X
And e DON'T write much new
right.
It's mostly a scavenger hunt, plus a general clean-up.
just put in in an order for each person to 'grok' drupal in their own way
I'm sure you'll find docs with incorrect / unclear info.
and clean as we go
yep.
well, that'd be a really good way to go about it, but I'm sorta curious as to how you've figure out how to server each audience their own set of info?
That, imo, is the way to do it.
Senpai: umm, with hyperlinks?
Senpai - what do yo mean?
Too many links = confusion for most surfers tho
Senpai: you put yourselves in their shoes. Or read up on support requests and jot down notes on the things these types of people talk about. Or just go find someone in that boat and ask them. ;)

Hm. I'm not thinking it would be just a big link farm.
I'm thinking there would be contextual information there.
webchick: sure,
But the main idea is, you're writing context around existing pages.
yes
And laying it out in a step 1, step 2...

right and it all comes in the form of a few sentences about how those all play together but links to their respective pages for more actual doc.
Senpai: once you guys get a good "I am a X and I'm looking for info on Y" section going, that might very well be a logical replacement for the /handbooks page.

webchick: OK - dammit, how do I start this... I can create a book on d.o? you say? or do I need to apply for doc team first?
samtresler: nah, anyone can create a book page.

Oh. The title of the section of the handbook that sam's making.
ahh
I'd call it "First Steps"
Yeah that's good.
Call it "Maurice" -- really confuse people. ;)
If it's targeting Business owners, coders, newbs, and graphic artists
Then it can branch down from there.
Ziggy! Call it Ziggy!
haha
*sigh*

Probably talk to Sepeck first? copy this conversation and let him take a look-see

OK - I'll start plotting.... I mean outlining
well. i just clicked the submit button. ;) not sure when my reply will actually appear, but.. ;)

Ok, I really gotta go back to work now. ;) Thanks for the chat though, that was awesome.
* Senpai has quit ("The computer fell asleep")
dojo slaves are now very busy!