[documentation] [Documentation feature] Create First Steps Handbook

Tue Jan 30 18:47:39 UTC 2007

Issue status update for 
http://drupal.org/node/114078
Post a follow up: 
http://drupal.org/project/comments/add/114078

 Project:      Documentation
 Version:      <none>
 Component:    Customization and Theming Guide
 Category:     feature requests
 Priority:     normal
 Assigned to:  Tresler
 Reported by:  Tresler
 Updated by:   Senpai
 Status:       active

"Samtresler said: Hey!, get your own issue... oh wait, you have one
here: http://drupal.org/node/113589

"
Sam is right. I'm gonna post my previous comment, complete with
sepeck's quote, over on that thread. If I don't, methinks the issues are
going to get REALLY confusing around here! ;-)

Senpai

Previous comments:
------------------------------------------------------------------------

Tue, 30 Jan 2007 04:12:50 +0000 : Tresler

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 at 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!

"

------------------------------------------------------------------------

Tue, 30 Jan 2007 04:59:09 +0000 : sepeck

I will mention that there is built in book type only search.  This is
available on the advanced search form.  You can also segregate search by
content type.
some terms type:book

I realize this is probably not what you meant but it is there and does
work.  When combined with additional term tags on the advanced search
page it works even better.

------------------------------------------------------------------------

Tue, 30 Jan 2007 05:48:29 +0000 : Senpai

"Sepeck says: I will mention that there is built in book-type-only
search. This is available on the advanced search form. You can also
segregate search by content type. [some terms type:book]. I realize this
is probably not what you meant but it is there and does work. When
combined with additional term tags on the advanced search page it works
even better.

"
Well Sepeck, from what you're saying, we *could* craft a set of links
that would allow users to search the section of the site that they're
currently on without having to wait for a module fix? (If indeed a
module fix is needed) and we could offer these stylized search links to
users starting tomorrow? I suppose the only question then is, "How do we
make these links stand out visually?" An inline link is not going to be
noticed by someone who's scanning the page for something block-like and
resembling a "Search This Section" box.

Ideas anyone?

------------------------------------------------------------------------

Tue, 30 Jan 2007 14:31:41 +0000 : Tresler

Hey!, get your own issue... oh wait, you have one here:
http://drupal.org/node/113589

;)