[documentation] Some thoughts

[Steven Peck]

Laura's answer is better but I wanted to address some of your assumptions.


On Tue, Aug 25, 2009 at 8:03 PM, adept digital
evolution<techlists at ade.pt> 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.
>
The docs have changed.  They have evolved.  I have hundreds, if not
more, of hours in improving the documentation.  Others have as much or
more as well.

Building a website is really not easy.  It's not.  And it is shocking
how simple Drupal makes something insanely complex look.  If you see a
lock, contribute, add, edit, improve.  A drupal.org user account has
this right on most documentation page.  No one is stopping peole from
contributing.

An hour is really not unreasonable.  You are having to deal with
multiple complex realms of information and it has been simplified
immensely.  Much of it new to you.  Databases, user accounts on a
database, permissions for a specific database, A programming language,
it's configured interaction with a web server and a database.  A web
server, which directory, where do the files go, how is it configured,
is it restricted due to shared hosting, special permissions because of
shared hosting....etc etc.  If you encounter problems, then you have
to learn how to convey the correct framing of the problem so that
people of different languages can understand why you might have an
issue and direct you to a solution.

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

Overhauls happen all the time.  I did the last 3.  They took me once
we agreed on an outline roughly 50-60 hours each time to complete.
Add1sun is working on one now.  (See issue queue).

If you are going to build and maintain a website, you will become a
bit of a geek.  You can't help it.  Unless you are paying someone else
to maintain your infrastructure you cannot help it.  If you are hosted
then all you have to worry about it your drupal install.  Roles,
permissions, proper input filters, htaccess files for your site and
updating modules/drupal when there is a security release.  If you do
that much alone, you are a bit of a geek, which is cool because that's
more people to help out others.

So, experience on your own computers.  Would that Windows, Mac, Linux?
 Already we are developing complexities of writing.  Do we document
tools with Windows clients, Mac or Linux?  All three?  To get improved
documentation all we need is for people to contribute it.  Please feel
free, your contributions will show up in the tracking pages and be
appreciated.


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

This hasn't changed.  This happens with every wave (including this
conversation).  This is how we get new contributors.  As a mention
though, I can think of 4 to 6 different ways to accomplish what you
just mentioned and that is for a simple site.

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

Yes and frankly it was one of my big disappointments that people
continually built content and put it on external sites instead of
contributing here.  People wrote and were paid for books and did not
contribute here.  People did videos and charged for them on third
party sites.  Not my fault.  Please, make some videos and contribute
them HERE!

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

Yes, this is not new, it happens every release.  By us you mean you
and some select group or are other people welcome to help?   I ask
because it should be a community thing.  Not some exclusive group.  In
a community people will drop in, contribute where they have time and
then step away again.  It is not you against me, or us against them.

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

Where did I limit my vision?  If you understand Drupal enough to set
it up, you know enough to build a website.  That makes you a geek in
my opinion.  However, I do this because people contribute back.  If
people are unwilling to contribute back, then I don't care if they use
Drupal themselves.  They can pay someone or use something else.  You
are free to work off a different vision though so it all works out.

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

Yes.  I was the documentation team lead for several years.  herding
cats and communities and getting contributors is challenging.
Ultimately it must produce work.  For free.

The most obviously available easy features.... for whom?  This is the
challenge.  For a blog site?  For a corporate brochure?  For a
community site that has multi-user blogging?  For whom?

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

Yes, but people keep writing books and not writing docs here for free.
 Very frustrating.

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

Nope, but you will now how to check the oil (security updates), you
will be familiar with the concept of security (hey webhost, somethings
weird, have I been hacked?).

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

I am not a programmer.  Most contributors are not.  In fact many
contribute docs because they are not programmers.  Please tell me
where I did not ask you to contribute?  Please show me somewhere where
I did not beg people to write documentation.  I am not a web
developer.  My web sites are a hobby.  I make no money from them.  No
one pays me to do them.  Please tell me where I claimed to be a
professional web developer.  Your assumption that I am part of 'they'
is not correct as it is not my profession..

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

You seem to think that I am some big professional web guy.  You seem
to be saying here that I am this 'they' that doesn't understand and
you have to make me.

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

Where did I say that you were?  Nowhere.  But please check the
tracking links in my earlier message.  Check the track records of
contributors and ranters who fail to contribute.

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

I could cry.  How am I (or this nefarious we) keeping you out?  Where
did I say you couldn't play?  Where did I say you couldn't contribute.
 You have a drupal.org account YOU ARE ALREADY IN!  You can contribute
right now!  You can edit pages, add pages, clarify the obscure.
Please please do not infer that I or anyone is standing in your way.
It is not a us against them.  It is an us pleading with people to
start writing.  Please start contributing.  Please edit and
improve,add new content.

> kazar
> --

You are subscribed to a technical mailing list.  You by definition are
a geek.  It's to late for you.  You must try instead to save the next
person to come after you.

Your passion seems to be to make it easier for neophytes and technical
illiterates to install and configure a Drupal site.  That is a worthy
goal.  We (the community) are happy to exploit it for the betterment
of all.  I had that goal at one time but most of the stuff I wrote was
edited out of existence or absorbed into different content.

My goal was to build a way for people to contribute to documentation
and improve what we had which would expose it to more people. I spent
years doing this and am fairly proud of what I helped accomplish.

oh yes.  For a more general answer, read Laura's email.

Steven Peck