[documentation] Barriers to entry...

[Ariane Khachatourians]

Re: Barriers to entry

Jennifer, I found it incredibly helpful having the PHP and HTML posted on
the standard page - being that I can write HTML but not PHP, but am
marginally PHP literate, that (and peeking at the patch you posted for a few
other hints) was enough for me to be able to adapt a help function on my
own, which to me is amazing! (And the closest I've come to writing any PHP
code.)

I don't really consider myself a "developer", and wanted to be able to go
further than just editing online docs, and I have been able to, but it of
course required effort and a willingness to learn new tools. And it always
will, because let's face it, this a web application, and it is made of
code!  No matter how advanced our APIs get, there is always going to be some
things you can't access or work on without working in the code itself.

I would hope that most people *would* have an inclination to learn further
(and if they choose not to, then that is a fair choice).  What I found
incredibly helpful getting to the point where, as still a non-developer (ie.
I don't know how to write PHP code) was this (and these 3 things seem less
scary as separate steps, so maybe focus on #1 and #2 as separate sessions):

1. Having someone walk me through setting up a local install on MAMP, use
PHPmyadmin, and getting a basic list of what commands I needed to know in
command line.

2. Having the issue queue/patch review workflow explained and shown to me,
along with learning the commands to apply and revert patches, do a diff, and
reset my codebase to HEAD.

3. And this is not *necessary* but having at least a willingness to learn to
read (and hopefully one day, write, code). I have so far self-learned HTML
and CSS (with help from friends and coworkers), and can sort of fumble my
way through reading PHP to the point where I can cut and paste things into
the right place. But that is something people have to be pretty self driven
to accomplish.

The biggest challenge is finding a way to make these things seem exciting to
people rather than scary, and the only thing I can attribute that to for me
is having very enthusiastic and patient people around me who have made
certain I didn't get discouraged.

Re: How to conceptualize the help system

Is there an issue filed on d.o somewhere about this? It's not been on my
radar - and I can only assume this is past the eleventh hour for D7 to try
and make that sort of a conceptual shift.  But that doesn't mean it's not
something worth thinking about some more.

And really, I do think the new structure of the help content accommodates
that user-focused approach better. The About section, being about what the
module does, and the Uses section telling you how it can be used.  No, it
doesn't give you a step-by-step on how to do things, but that is in the
handbook.

Ariane
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.drupal.org/pipermail/documentation/attachments/20091114/09d4bee2/attachment.html