[documentation] Some thoughts

Fri Aug 7 22:04:44 UTC 2009

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