[documentation] Some thoughts

[adept digital evolution]

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)