[documentation] Some thoughts

[Steven Peck]

On Tue, Aug 25, 2009 at 4:07 PM, liza<nyc.blogdiva at gmail.com> wrote:
> HUNTING AROUND is not user friendly.
>
> Telling people they ought to know how to run a command line, is not user
> friendly.


I have to disagree with this.  No one is telling people they have to
run a command line.  Really they aren't.  Someone provided
instructions at some point was command line based.  Why?  Because that
was the best tool at the time.  They took the time to transfer
knowledge.  This is not unfriendly, this is not hostile.  This is
merely a set of instructions.

People for years have been able to add to the instructions.  Many have
done so.  Many have expanded on how to do this.  Some have done so
with step by step instructions and expansions on this process.  Some
have built tutorials with GUI tools.  This is all cool and the result
of the community contributing for free.  The sheer volume of
documentation has prompted re-orgs and edits.

Drupal.org is a living site subject to the time people have to
volunteer and contribute mostly for free.  I know for free because
there is a lot of money floating around Drupal land and I have
received none of it.

None of this is unfriendly.  Saying it is kind of denigrates the
contributions of people that tried to help.  This drives contributors
away.  Even that cousin you don't agree with who is contributing to
the community.  It is merely documentation.  Can it be better?  Click
on the edit tab and please make it so.

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

People contribute for their own reasons.  Many people here are geeks.
Being a geek and wanting to contribute is not a bad thing.  Many geeks
do in fact contribute with the view towards making things easier for
the next generation of Drupal users.  A whole lot of people in fact,
hundreds have.

We have a lot of people here who are more then happy to help you
become a geek and convince people to document the knowledge they learn
on the road there to benefit the next generation of Drupal users.  And
no, if you implement a Drupal site, you are or will be a geek  when
you are done.  Geeks often go on to lead happy, healthy productive
lives so this is not a bad thing.

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

Yes, it's interesting but not really relevant to documentation.  It's
a variation on his previous speeches but frankly kind of tired of the
speech after two years.  This is a classic case of code is gold.  It's
nice that people have the energy to 'hate' but not useful,
constructive and as far as I can tell, has not yet actually
contributed to building better things for the community.

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

This is really not at all useful.  Pretty much the most alienating
thing you can do to all the people who have tried to contribute is
tell them that they fail.  What you could do is write some
instructions for areas you believe are weak (I am fairly certain I
have even said this before).  Edit existing instructions so that they
come up to your standards.  The permissions on the book pages are set
up to allow for this.  And we can all see who actually contributes
documentation and who actually edits to improve documentation.  After
a year with Drupal, pretty much anyone who wants to improve Drupal
documentation should be on these lists at least once.

http://drupal.org/node/14205
http://drupal.org/node/263594

> 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).

This doesn't really have much to do with documentation because
everyones list of 'recommended' modules will be different depending on
their needs.  Having glanced at 'simplepie' module, I could possibly
see a use for it so would never get as far as the how to use part.
Not sure why it's relevant.

This is a community.  We don't 'direct' people to do things, we 'open
up' and allow them to contribute.

> 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 outside the scope of community user friendliness and into a
much different arena.

I'm just going to stop here.

Steven Peck

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