[documentation] Some thoughts

[Steven Peck]

In the few years I was privileged to be doc lead, I worked hard to get
people involved and build the documentation contributors and people
working in the support forums.

I learned a few things that have not changed.

Getting people involved is important.
Getting people involved can be time consuming.
Getting people involved can get you attacked.
Getting people involved can be rewarding.
Getting people involved can lead to burn out.

Everyone has radically different ideas on what 'Getting people
involved' means.  What a given group of people find as normal will
quite possibly offend/annoy/aggravate others.

As our community grows it will change and what some people find 'off
putting' others find 'normal'.  When new people come in and say they
find the 'current community unfriendly' that alone often ruffles
feathers and sensibilities.   When people try and help in their own
way, they get chastised themselves and told to 'behave' in some
fashion.  This thread had some of that occur and the urge to
'chastise' some can act as a method to drive existing contributors
away.  I myself had to stop for a while because of work/life issues
outside of Drupal didn't allow me the luxury of dealing with the
stress of some folks in the community caused me.

This is an open source community and every community has that 'awkward
cousin' (and who it is is different depending on your perspective)
whose approach you disagree with.  That's life and we as a community
need to help people understand that their cousin will be at the picnic
but they don't have to hang out with them.  Hopefully that analogy
will work for people.

Have fun at Drupalcon.

Steven Peck

On Fri, Aug 21, 2009 at 5:20 AM, Addison Berry<drupal at rocktreesky.com> wrote:
> Rarg, sorry it took me so long to reply to all of this. My response here
> isn't right on with all of the initial things that Shari raises, but is a
> more general discussion. I've been thinking this sort of thing over for a
> good while now, since getting more people involved, in ways that aren't
> weird, standoff-ish or confusing, is a major concern for Drupal particularly
> and OS generally. A full half of the "docs roadmap"
> [http://drupal.org/node/488070] is people/outreach (versus the docs
> themselves).
> We started out by looking at rewards and what people want, but over time it
> becomes more clear to me that we really need to focus on the goal of "Foster
> relationships between people," which is the first thing in the App. B goal
> list [http://drupal.org/files/roadmap-AppendixB-outreach-tasks.pdf]. The
> four main starter, brainstorm tasks that we have under there are:
> - Identify missing people (SMEs - subject matter experts)
> - Connect Mentors to Mentees
> - Connect Peers to Peers
> - Connect Humans to Topics
> I'd love for us to get a group of folks to sit down and really hash out what
> these tasks entail, organize tasks to find some answers and come up with
> suggestions. I think the most pertinent to the discussion this post started,
> and generally all new folks trying to figure things out, is the
> mentor/mentee task. Ideally we need people involved from both sides of it:
> people who already "get" the community and docs work in particular, and
> folks who are new and trying to figure out WTH is going on.
> Ideally we can have some discussions/surveys/brainstorming that will result
> in concrete things we can try out. As in, what kind of framework/tools can
> we provide? What are the resources we already have? What are our
> restrictions? Can we change that or how do we work within them? As a new
> community member, what are you looking for? As an experienced community
> member, what would make it easier for you to help others?
> If anyone will be in-person or online during DrupalCon Paris, I'd love to
> chat about this (I'm add1sun online and if you can't find me at Drupalcon,
> I'll definitely be at the doc sprints ;-), and you can always ask folks to
> point me out anytime during the con. I don't bite. Really. I also do
> encourage everyone to talk about this on the mailing list since lots of
> people won't be in Paris and this is a big issue I'd love for us to tackle
> as a team.
> - Addi
> On Aug 7, 2009, at 3:57 PM, Shari wrote:
>
> Hi my name is Shari, and I've been a member of this group for a long while
> (actually forgot). I joined drupal.org over 2 years ago. I've started and
> stopped working with Drupal over and over. I am however recommitting myself
> to actually sticking with it. I plan to do this by investing my time &
> money, and that means also giving back to the community. However it's been
> my experience in the past, and again that although it's everywhere that
> Drupal wants people to join in, and to make Drupal user friendly, this isn't
> my experience.
>
> I joined the documentation originally because this is the 1st thing anyone
> new sees, if it doesn't make someone feel included & that it is
> understandable, they're gone.
>
> Out of the CMS's that are out there that I've tried and looked into I chose
> Drupal originally for 2 reasons.
> 1. It can grow as my experience grows.
> 2. People actually answered my questions in the forum.
>
> I've walked away from Drupal for 2 main reasons.
> 1. Documentation is way over my head.
> 2. Outside of the forum, it feels unfriendly.
>
> I got started today by looking for something I could do, and went with the
> Documentation Issues for D7. Review and update the Installation guide. So
> started at the installation instructions and downloading D7. Right off the
> bat, I noticed it saying "This documentation focuses on performing tasks at
> the command line." Maybe I missed something but, that right there is not
> user friendly. I've installed Drupal any number of times, and I still don't
> know what the command line is. Most people who know nothing about Drupal and
> want to install it, are going to start with the Installation Guide, and
> right off it's made Drupal feel like if your not a programmer or someone who
> is familiar with the "back end" of a system you should turn around.
>
> So I wondered where should I discuss this, I jumped into the IRC channel
> posted just that question "Where is the best place to discuss
> documentation?" There were 25 people sitting in the channel, I waited over
> 25 minutes and never received a response. Why are you in the channel if your
> not going to chat?
>
> Unfriendly feeling... again.
>
> If Drupal truly intends to appeal to people outside the "geek" community,
> this is the 1st thing that needs to be addressed.
>
> What can I, what is the 1st step, I can take towards making that happen? Do
> I post a comment to the issue about my thoughts on it. Do I go into the IRC
> channel, do I post to this mailing list. Where does the discussion begin,
> and happen?
>
> I'm willing to do something, I just need a bit of help getting there.
>
> Shari
> WebWeaver64 @ Drupal.org
> --
> Pending work: http://drupal.org/project/issues/documentation/
> List archives: http://lists.drupal.org/pipermail/documentation/
>
> --
> Pending work: http://drupal.org/project/issues/documentation/
> List archives: http://lists.drupal.org/pipermail/documentation/
>