[documentation] [Documentation feature] Create First Steps Handbook

Gus Austin gus at pepperalley.com
Wed Jan 31 18:06:43 UTC 2007


I think everyone has - they're a tremendous resource! I forget now if
there is going to be dojo/lesson specific docs on drupal.org.
Regardless I don't think anyone's (on the dojo or drupal.org) NOT
going to want great documenters.

On 1/31/07, Victor Kane <victorkane at gmail.com> wrote:
> Hi!
> Have you noticed the class notes I have been providing after each class?
> Do you think we should work together in some way?
> Can I be a dojo-documentation guy too?
>
> Victor Kane
> http://awebfactory.com.ar
>
> On 1/31/07, Tresler <drupal-docs at drupal.org> wrote:
> > 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:   Tresler
> >  Status:       active
> >
> > Gusaus, I think my current plan is that these will just be book pages
> > that provide different ways through the current documentation.
> >
> >
> > I'm not so sure that you have drifted off topic here, as this project
> > has drifted off the topic of the original conversation.  I still *do*
> > want to pursue using the dojo as a filter to roll disparate content back
> > into the handbooks, as in an ideal world, they would all be reading all
> > the 'pre-reading' they could and would be in the best position to edit
> > handbook pages for what was useful to different levels of beginners.
> >
> >
> > However, I think this has ow become a seperate projet and we should
> > pursue that one through the dojo-channels.
> >
> >
> > Now, in relation to that, I'm happy with my new documentation role to
> > act as the dojo-documntation guy (or guys with Senpai and anyone else
> > willing t take up the gauntlet) - and help get *that* ball rolling as
> > well.
> >
> >
> > Later today, as I get time, I'm going to attempt to outline the paths I
> > want to start working on.
> >
> >
> >
> >
> > Tresler
> >
> >
> >
> > 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
> >
> >
> > ;)
> >
> >
> >
> >
> > ------------------------------------------------------------------------
> >
> > Tue, 30 Jan 2007 18:47:39 +0000 : Senpai
> >
> > "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! ;-)
> >
> >
> >
> >
> > ------------------------------------------------------------------------
> >
> > Tue, 30 Jan 2007 22:34:45 +0000 : gusaus
> >
> > Geez - glad I found this as I'm currently in the process of sorting thru
> > most of the same IRC chat (as you did above). I'll help with this any
> > way I can (although you prob. don't want me writing documentation). A
> > few issues, I think we discussed, was to see of we could provide a means
> > to 1) syndicate the materials in this centralized handbook (provide RSS
> > feeds?); and 2) aggregate materials  scattered about g.d.o., other
> > drupal sites, mailing lists and related IRC channels. While the
> > following sites do provide rss feeds, I'm not sure how realistic (or
> > desirable) it will be to aggregate (and filter) in this centralized
> > repository.
> > http://drupaldigest.com/
> > http://drupal.org/planet
> > http://groups.drupal.org/
> >
> >
> > Apologies if I drifted to far off topic...
> >
> >
> >
> >
> > --
> > Pending work: http://drupal.org/project/issues/documentation/
> > List archives: http://lists.drupal.org/pipermail/documentation/
> >
> --
> Pending work: http://drupal.org/project/issues/documentation/
> List archives: http://lists.drupal.org/pipermail/documentation/
>


More information about the documentation mailing list