[documentation] Some thoughts

[Laura]

Ultimately, the answer to this entire discussion is this: the Drupal  
community is a do-ocracy. Those who do are those who decide. What you  
experience, what you see in docs, what you see in code, is there  
because someone did it. And they contributed it for the bare minimum  
fact that they did it. Nobody is paid to do this. Yes, some people are  
paid doing Drupal work, obviously. Many on this list, including me,  
count among that crowd. But that doesn't mean that we are paid to do  
Drupal's work. Everything happens because someone stepped up and shared.

Criticism is helpful. It's a start. But if you aren't willing and able  
to step up and follow up that criticism with contributions, then it's  
just kibitzing.

Everyone new to the Drupal project is in an ideal position to improve  
the introductory docs, including basic installation. That is one of  
the first things I did when I joined the community some years ago.  
When you are new, the questions are fresh, the uncertainties are  
clear. And when you figure out or learn the answer, you are the ideal  
person to share that information with others so they don't have to go  
through the same struggle.

The thing that seems to elude a lot of people -- the /fact/ of an open  
source community -- is that nobody owes anything to anyone. We  
contribute because we want to, not because you are somehow owed  
something better. If you see a better way to explain things, then  
create a new page and explain it! Make it a sub-page of the  
installation page, and call it, "Instructions in case what you just  
read did not make any sense to you." Believe you me, if the  
instructions are good, people will thank you for it!

And suddenly you are a part of the community, participating in the  
collective creation of the commons that we all share in. We all do  
what we can to make it better. We code. We document. We design. We  
help others. We support others in these things. Why? Because it's in  
our interest. I do it because by doing so I'm somehow making things a  
bit better, a bit easier for others, and that it turn brings back to  
me benefits 1000-fold.

So my suggestion -- no, my request -- to you, digital evolution, is to  
share what you learned in your hard-earned personal experience so that  
others don't need to follow in your footsteps. There are no  
gatekeepers. Anybody with a Drupal.org account can add a documentation  
page. Just do it. In this community, it's easier to win forgiveness  
than to gain permission.

Laura


On Aug 25, 2009, at Tue 8/25/09 9:03pm, 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/