[documentation] Some thoughts

Tue Aug 25 23:07:20 UTC 2009

HUNTING AROUND is not user friendly.

Telling people they ought to know how to run a command line, is not user
friendly.

Please consider there's a whole class of people who are not interested in
being F/T geeks. There are way more web site builders and architects out
there than Drupal coders or engineers. These are people who are looking to
being empowered with user-friendly tools that we can use for cranking
powerful yet user-friendly sites. If Drupal boasts to be both powerful yet
easy to use then, for heaven's sake, let it actually work.

I really, really, really recommend you all catch Walkah's "Why I hate
Drupal" speech from this year's DrupalCon-DC

Here's the SlideShare:
http://www.slideshare.net/walkah/why-i-hate-drupal

Here's the Video:
http://www.archive.org/details/DrupalconDc2009-WhyIHateDrupal

That's me testifying in the background :)

Am slowly putting my rants and rave into a Drupal Notebook over at
lizasabater.com and my #1 complaint is how poorly a lot of the instructions
are written IF AT ALL.

There's a lot of "recommended" modules that ought not to be because they
have no documentation or the instructions are misleading because the module
hasnt been tested against modules with similar 3rd party dependencies (am
thinking of the SimplePie mess).

We should follow Firefox and the modules that actually work go to the front.
The ones that need thorough testing and/or documentation should be put into
an "experimental" category: Not quite recommended but not quite DEV either.

This is not quite a derail because we are still contending at Drupal.org
with the sheer volume of module and themes being added to the site. If there
were a system that would better identify the non-user ready modules that
need further testing and/or documentation, it would make the life of people
like Shari, Ylyse and yours truly to jump in and lend some documentation
and/or testing work.

So, am just putting it out there because, as nice as it is to have people
working on Drupal 7, there's tons more documentation that needs  to be taken
care of when you look at contributed modules and the need to start putting
together user-targeted distributions.

/ liza

Liza Sabater
http://culturekitchen.com
http://dailygotham.com
http://lizasabater.com

FriendFeed: liza
Twitter: blodiva

On Fri, Aug 7, 2009 at 6:04 PM, Steve Dondley <s at dondley.com> wrote:

> And let me play devil's advocate here.
>
> You may find some people who are willing to hold your hand for some
> length of time for free, but they will be few and far between. You
> should have no expectations of that and count your blessings when you
> do.
>
> To really succeed, you need to be self-motivated and develop a love
> for the pleasure you feel when you stop banging your head walls for
> several hours. The 25 min. you spent waiting for an answer form others
> could have been hunting around on drupal.org finding an answer and
> googling what the command line was.
>
> So what I'm saying is, you need to get over the "unfriendly" feeling
> you have when someone doesn't immediately respond to your question.
> You are owed nothing.
>
> My advice is to just put your head down, work hard, bang your head on
> the wall, take pleasure when you figure something out, find something
> else to do if you get stuck, contribute when you get a chance, and
> count your blessing when you find someone who takes the time to give
> you advice. But the bottom line is, free advice and a helping hand
> will take you maybe 20% of the way there. The rest has to come from
> within.
>
> On Fri, Aug 7, 2009 at 5:10 PM, adept digital evolution<techlists at ade.pt>
> wrote:
> > On 08-07-2009 3:57 PM, Shari wrote:
> >>
> >> Hi my name is Shari, and I've been a member of this group for a long
> while
> >> (actually forgot). I joined drupal.org over 2 years ago. I've started
> and
> >> stopped working with Drupal over and over. I am however recommitting
> myself
> >> to actually sticking with it. I plan to do this by investing my time &
> >> money, and that means also giving back to the community. However it's
> been
> >> my experience in the past, and again that although it's everywhere that
> >> Drupal wants people to join in, and to make Drupal user friendly, this
> isn't
> >> my experience.
> >
> > Shari, I'm coming from exactly the same experience. While I do have a
> strong
> > technical background, stronger than perhaps 98% of the general public, I
> am
> > not a programmer. But someone with my level of exposure (slightly more
> > teckie than yours) should not have a hard time with a simple installation
> > and in the past I have.
> >
> > So I am also committing to working on the D7 installation guide.
> >>
> >> I got started today by looking for something I could do, and went with
> the
> >> Documentation Issues for D7. Review and update the Installation guide.
> So
> >> started at the installation instructions and downloading D7. Right off
> the
> >> bat, I noticed it saying "This documentation focuses on performing tasks
> at
> >> the command line."
> >
> > I use an ftp client program that I believe can handle everything one
> needs
> > to do for an installation, without asking Windows users to use the
> command
> > line (Command prompt on Windows, Terminal on Mac and Linux) ...  without
> > having to learn to "ssh" to a remote server (most of us use web hosts in
> > another city or even country, right, as opposed to sitting right in a
> room
> > with their web servers?) etc.
> >
> >> Maybe I missed something but, that right there is not user friendly.
> >
> > I agree. With all appreciation and all due respect to Tom Geller who took
> > the first swipe through creating the D7 guide, I would like to see the
> docs
> > discuss  using ssh (for the more technical audience) or a friendly ftp
> > client (for folks like you and me) to install on a computer one does not
> sit
> > in front of.
> >
> > Please tell me if this is not the case with you, or if you simply do not
> > agree, but I would think that among those who like us are not
> programmers,
> > we are not trying to serve a Drupal site from our home computer. We need
> to
> > understand how to upload and install Drupal on a computer "somewhere else
> on
> > the internet". True? Or is this a misconception of mine colored by my own
> > situation (although I must say that of the hundred or so colleagues I
> have
> > in my - technical - field, very few of them maintain their own web
> servers
> > in their office)
> >
> >> I've installed Drupal any number of times, and I still don't know what
> the
> >> command line is. Most people who know nothing about Drupal and want to
> >> install it, are going to start with the Installation Guide, and right
> off
> >> it's made Drupal feel like if your not a programmer or someone who is
> >> familiar with the "back end" of a system you should turn around.
> >
> > i agree that docs in the past tend to make one turn tail and run. So
> perhaps
> > you and I can provide the perspective that's needed to be "user testers"
> and
> > to help revise the docs to be completely understandable and usable by
> folks
> > like us (who are, I had thought anyhow, the target "market" for Drupal
> ...
> > "no need to know web programming" etc)
> >>
> >> So I wondered where should I discuss this, I jumped into the IRC channel
> >> posted just that question "Where is the best place to discuss
> >> documentation?" There were 25 people sitting in the channel, I waited
> over
> >> 25 minutes and never received a response. Why are you in the channel if
> your
> >> not going to chat?
> >>
> >> Unfriendly feeling... again.
> >
> > i have found this list to be very supportive of newbie doc contributors
> like
> > us. At least here you've found me, who doesn't know PHP from MSG, lol.
> >
> >>
> >> If Drupal truly intends to appeal to people outside the "geek"
> community,
> >> this is the 1st thing that needs to be addressed.
> >
> > hear, hear! I think the folks here know this. It seems to be on the scale
> of
> > a passionate misson on this list and under Addi's leadership. (If you
> don't
> > know who she is you will soon.)
> >
> > I know, because I have felt it myself, that it can seem like trying to
> break
> > into a clique when jumping into an OS project. (For example, "who is
> Addi?")
> >  I don't for a second believe that is the intention of the people here,
> but
> > it can just _feel_ that way because other folks already know each other,
> are
> > familiar with efforts that are underway, already understand the do's and
> > don'ts of modifying site content, and all of that. But we'll catch up,
> and
> > so far my experience is that those who have been on this project a while
> are
> > patient and friendly.
> >
> >>
> >> What can I, what is the 1st step, I can take towards making that happen?
> >> Do I post a comment to the issue about my thoughts on it. Do I go into
> the
> >> IRC channel, do I post to this mailing list. Where does the discussion
> >> begin, and happen?
> >>
> >
> > Addi (the lead for this D7 docs project) has told me, when i asked the
> same
> > kind of question, that most folks actually open an Issue for discussions
> > like this. It's another twist in the more-than-odd Drupal semantics. In
> my
> > entire 25-year-long career in computer applications, an "Issue" has
> always
> > been a big, and, in some systems, might be a feature request. But not a
> > simple topic for discussion.
> >
> > But since you asked here I'm answering here and I'm sure nobody will
> spank
> > us! (right?)
> >
> > I have a proposition for you, Shari. This weekend I will be setting up a
> > test site to install D7 and will be making mods or, more likely for now,
> > comments against the text that Tom (Geller) started. My intent is to
> provide
> > alternative or supplemental text where the instructions are confusing, or
> > where they might be made easier by explaining how to accomplish an
> > installation using more user-friendly tools. When I am done I will
> contact
> > you and ask you to try installing again with my new notes and mods added
> to
> > the instructions.
> >
> > I am planning to get my site set up tonight and to run through the docs
> by
> > tomorrow night or very early Sunday.
> >
> > Are you game?
> >
> > ilyse
> > (kazar @ drupal.org)
> > --
> > Pending work: http://drupal.org/project/issues/documentation/
> > List archives: http://lists.drupal.org/pipermail/documentation/
> >
>
>
>
> --
> Prometheus Labor Communications, Inc.
> http://prometheuslabor.com
> 413-572-1300
>
> Communicate or Die: American Labor Unions and the Internet
> http://communicateordie.com
> --
> 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/20090825/6ffecb27/attachment.htm>