[documentation] [Documentation feature] Create First Steps Handbook

Wed Jan 31 16:47:01 UTC 2007

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/
>