[documentation] Some thoughts

[Jeremy John]

When I started Drupal, I had no idea what the difference between SSH and 
FTP was. Now I run Linux as my primary OS.

I spent hours agonizing over documentation that was sparse and terse. I 
persevered mainly because I am extremely stubborn.

There are weeks of my life I devoted to reading about Drupal modules, or 
a day I spent before realizing that I had to be user 1 to configure a 
module. Newbie errors that may seem obvious. Of course I never chmodded 
anything, and my installs were insecure.

I sometimes think of all the hours of work that we replicate, 
discovering things that others have discovered and which are now obvious 
to them. I think that documentation is an excersise in flushing out our 
own assumptions and learning to communicate what is natural or obvious 
to us.

I wonder about the drain upon the economy and the lost efficiency. And 
then I think about what full and complete documentation could save in 
terms of monetary gain for the economy and generalized frustration.

Peace,
glass.dimly

adept digital evolution wrote:
> 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
> -- 
> Pending work: http://drupal.org/project/issues/documentation/
> List archives: http://lists.drupal.org/pipermail/documentation/
>