What Drupal documentation means to me

Last Friday Dries announced that Steven Peck (sepeck) had decided to step back from his leadership role on the documentation team. Steven and Dries asked me to step into those big shoes and I accepted. All I can say is that I am glad that Steven isn't going away. :-) I'm honored that two people I respect so much have thought me worthy of this title. I will definitely hearken back to the many lessons I have learned from them both and strive to not disappoint.

The Drupal project has long stood out for copious amounts of documentation. With the Drupal.org redesign under way and exciting work going on for Drupal 7, there is a feeling of great change in our community. Of course, Open Source in general and Drupal in particular thrives on change. Drupal has been growing and shifting and I've been feeling lately that the leadership of Drupal in the Open Source community is not confined to just our software and our community, but that Drupal documentation can and should become a leader in the field too. We've got a passionate community of people from all over the world, with more varied skills than I can name. We have all of the pieces to not only create even better docs for Drupal, but to push documentation in new directions and set new standards for Open Source, both in quality of content and in organization and focus of our community efforts. I truly believe that the team I have worked with for the last two years is a top-notch group of people and together we will be a "best practices" example for how to "do docs right."

Dries outlined the responsibilities of a team leader in his post and while I am determined to further all of those goals, here are some immediate areas of focus for me personally. Everyone should bring their own passions to the table - you don't have to be a designated "lead" to make important things happen. So, here are my targets, to which I welcome and encourage you to add your own:

  1. The Getting Started guide: This guide was given an amazing foundation, laid by sepeck. He spent many, many days, weeks, months forging the initial guide for Drupal 5. He saw a great need for a tightly organized document to lead people through those first, sometimes harrowing, steps of using Drupal. We need to continue the care and feeding for this most invaluable resource. We need to keep it up-to-date and I'd love to see more of this central documentation directly accessible from within Drupal itself; maybe something like a new Help system in core or even a documentation module that uses the Advanced Help module in Drupal 6.
  2. Improving tools on Drupal.org: The redesign of Drupal.org is going to change a lot about our home for the better. It is long overdue and the excitement is palpable. As a community we need to pay keen attention to the changes we make and I am particularly attuned to a documentation wish list. How can we use this opportunity to not only make it easier to read the docs, but also make it easier for everyone to help tend our garden? The easier it is for us to maintain and care for our handbooks, the nicer it will be to stroll amongst them.
  3. Lighting the path to help: Many people have a lot of enthusiasm to help but do not know how to apply it. One of the great things about Drupal is that it is an Open Source do-ocracy. It can be one of the most frustrating as well. For people who do not feel comfortable just striking out on their own, it can seem too intimidating - the carousel is spinning too fast and requires too much bravado to jump on. For others, they may charge ahead and, in all earnestness, step on the wrong toe or accidentally kick someone in the shin. That can often lead to a bad experience for everyone involved and hamper further efforts to get involved. While I hope that the new Getting Involved guide will be the start of a better "lighted way" for folks, I want to spend a goodly amount of time focused on the iterative process of giving folks a clearer path to helping with the documentation, which will hopefully improve the documentation about documentation. :-)

These are three salient goals right now. Underlying all of these is another, which is not so much task oriented as it is attitude. I am buoyed not only by the greater changes in the Drupal community right now, but the real energy, insight and desire of the documentation team I get to work with every day. I feel that we have great opportunities before us and I am inspired to plow ahead with gusto. My current working mantra is "Throw it on the wall and see if it sticks." By this, I mean that I want to try new ideas, try old ideas in new ways, stretch boundaries and see what works. If things don't work, look at why, but then move on. Drupal has thrived on this attitude for many, many years. It is certainly nothing new that I bring, but I want to really encourage people to play in the finger paints - get your hands dirty and see what beautiful and sometimes unexpected things you can make. We can not only make Drupal more accessible and understandable, but we have the community - the people, knowledge and desire - to make real change in what the world expects of Open Source documentation. Feel free to join in the fun.


Congratulations on the offer/acceptance!

Beyond that, I have to say that point 3 above is one that has caught me up. When I was just starting out myself, I wanted to know where I could help, and people mentioned the docs team. I joined up, however it seemed quite a large bit of the project, and I didn't know where to start, and was a bit afraid that I wasn't even the least qualified to help anywhere. Everyone else seems so much more experienced here.

Over time, I have discovered that all of the people here are just plain awesome, and that really I have nothing to fear. So, shoving my apprehension into a dark corner, I contributed a few very small things. No one screamed at me for kicking their shins, and I discovered that I didn't have to digest the entire project to help out in some small way.

Having said that, I can see there is room for improvement there as well. There _should_ be a way to alleviate that apprehension, so that people might feel ok about jumping in, the right way.

Though, even if we write the most soothing, and informative docs, people still need to read them :)

i would echo crashtest's feelings as well.

for me, it really wasn't until i went to the documentation sprint that i "got" it.

i think you're doing a great job already: focusing efforts and attentions- first in the "get involved" book, and now the getting started book. i was going to jump into the themeing pages, but i see the getting started area needs TLC first. it's a logical order.

glad someone is directing this effort.

Just wanted to say best wishes on the new "gig"!

I want to thank you for your great dedication to the Drupal Project not as a Drupal.org member but as an individual that for many decade was looking for productive and creative goals. I can whit serenity witness that I necer was able to join a working group accepting aithority with easyness. Drupal.org show me that is possible to be part of a productive, creative and successfull community that provide tools to reach a kind of indipendence hand by hand remaining a respected human individual. Today as an active cooperator in the Drupal Community I can learn and appreciate the positive influence that raise from understanding roles and priority in one of the best free collaboration environments that the Open Source Sofware community offer to anybody. I thank here you, your predeccessor so as Dries Buytaert and all his staff, better his friends that made all this possible.

Thank You

I can't think of anyone better suited to fill those amazing shoes-- I look forward to you bringing your energy and enthusiasm to the documentation team!

Not sure if this is the proper place/time-- but one thought I've had rolling around my head regarding the handbooks is that while opening up editing to authenticated users is a great idea, i think page creation and placement needs to be reigned in.

While having page creation open to the world is awesome for wiki style documentation, I've found in the past it's exactly inappropriate for technical documentation which, unlike wikis, does have an optimal structure.

I'm an RTFM freak-- i'm one of those geeks who RTFM for every new thing i attempt before anything else and I'm intimately familiar with the d.o. documentation. IMO the docs themselves are quite amazing-- the main problem, and the reason why most newbies (who tend to browse rather then search at first) can't find anything is the harum-scarum structure that resulted from people creating pages and sticking them anywhere they thought it might make sense.

There's a lot of work going on with the d.o redesign and I'm sure you'll being doing even more with the docs team. Structure is likely to be a large part of that-- having new pages able to be created anywhere by any authenticated user will merely dilute that hard work on structure and put us right back where we started.

I honestly believe handbook pages should be created unpublished and modr8'd by the docs team to ensure they are placed in the optimal location. I know that does add some work, but I think it's the only way to avoid having the structure degenerate. To that end, i'm willing to put my money where my mouth is so to speak and volunteer my time should you decide to go that route.

Sorry to blabber on so long-- that ended up far longer than I expected, lol.

And again-- congrats!

Yep, I agree on your thoughts re: pages. I'd like to let the open editing rights settle down and, in evaluating the success or failure of that, I think it would be a good time to asses what we are doing with other rights.

The redesign is definitely going to be addressing lots of dark corners of documentation. Please hop in with thoughts on the Rethinking documentation thread which is where we are focusing on this very kind of thing.