[documentation] Some thoughts

[adept digital evolution]

On 08-25-2009 8:54 PM, Steven Peck wrote:
> 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.  

But to a new user coming to the site and downloading, the only 
instructions given in the Installation Guide *are* for doing it from the 
CLI. Speaking from my personal experience about a year ago, it took me 
HOUR to learn what I needed to know to follow the instructions as 
written. I'm sure they worked well when the only folks interested in 
using Drupal already had a background in web servers, CLI shells, 
php.ini settings and the like. But the demographic, I believe, has 
changed rapidly and the docs have not.

Some of us are interested in changing this but it would entail such a 
complete overhaul of the install docs to make them really friendly to 
the person who does not want to, or cannot afford to, become a "geek" to 
the level of understanding chmod, chown, how and where to find php.ini, 
and the like. Increasingly folks just want to make their own site, and 
if they want to make it content-driven Drupal is going to be one of the 
first tools they hear about or stumble upon. We have experience 
installing applications on our own computers and that is pretty much 
"it" (not that I expected installing something on a web server would be 
as easy, but even as someone who is pretty much at the power-user level 
on a personal computer I was shocked at how hard it was to achieve a 
successful installation with Drupal, using the installation docs that 
were downloaded with the package and which are for the most part only 
repeated in the actual Installation Guide book pages on the site.

Most folks start out  just wanting to install, have a home page, be able 
to add news items or blog content, play with a couple of themes. This 
was the case with me, and with several others who have chimed in on this 
thread ... and, I believe a huge percentage of the next wave of Drupal 
users.

Lucky for me I finally discovered a video on lullabot.com explaining how 
to install by ftp (thanks addi!!!) and it was ONLY because of this item 
on an external site that I finally "got it".


A few of us are right now going over the install docs and I am adding 
some minimal additions in hopes of making them more friendly to the 
newbie and/or average computer user who maybe never dealt with 
installing something on a web server before. The docs actually need a 
real overhaul but there just is not time right now -- the non-negotiable 
requirement for now is they must "work for 7".

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

Now it's my turn to disagree. And I say this from the standpoint of 
someone who for two decades, in the roles of PM and architect and 
general tech consultant to non-technical business owneres -- but to 
limit the vision of the future user-base of Drupal to people who Will Be 
Geeks, Dammit, By The Time They're Done is, IMO, an odd goal to 
champion. Nobody is saying there is anything wrong with being a geek. 
I'm halfway there myself and quite enjoying it. But good software, and 
good documentation, is written so that one can "just get going" by 
following a very easy Get Started Guide and by using the most obviously 
available easy features that should be most visible.

Then, sure, the docs and the application should provide deeper and 
deeper levels of information, and more and more sophisticated features 
for the person who wishes to keep learning.

Your last sentence quoted just above sounds to me like, "If you wish to 
drive a car, you are or will be a racecar mechanic when you are done."


Your other points are well taken about the passion and generosity of the 
community that has contributed over a long period to everything that is 
Drupal at this moment.

But I feel that there is also a resistance going on to what several of 
us Non-Geeks have chimed in here to say:

"We Are Here. We want to use Drupal. Largely due to the situation with 
the docs, we are finding it more of a struggle than it needs to be. We 
have the utmost respect for the programmers and more technical folks in 
this community, but, no, we don't have time to learn as much as you 
know, any more than you have time to learn everything about our 
professions."

Most folks who "need a web site" are students, artists, community 
activists, micro-business owners who live in the 21st century and 
therefore must have (and want to have) a web presence. We are excited 
about the potential of Drupal to serve our needs. We don't have budgets 
to hire someone else to install it for us, though we understand that 
once we wish to branch out beyond the core features, or wish to use a 
customized theme or certain modules, we probably will need to find a way 
to hire some help.

But, the fact is, if folks can't even get it installed so that they can 
play with it a while and get "sold" on Drupal, they will just go 
elsewhere. "Too hard." Too scary, when the docs actually start off by 
saying: "This guide focuses on installing Drupal 7 on a remote server 
running *nix (Linux, Unix, or similar) and performing tasks at the 
command line."

We are not here to bash!!

We want to help bring all of your good efforts to the masses in a way 
that will cause buy-in rather than rapid defection.

Maybe you'll let us in without insisting that we need to bring our level 
of knowledge about the geek stuff up to your level of knowledge.

kazar