Documentation: please help fix what's already there

Tonight I spent about two hours cleaning up the multi-site install instructions on drupal.org. Mostly I was trying to roll in some comments and generally tidy what had already been written. I noticed that the documentation for multi-site is sorely lacking though. There are a lot of really great tutorials that exist somewhere other than d.o (I'm looking at you Kevin, and you Jam!), but the information hasn't been rolled into our Official Documentation. Multi-site is just one example where Drupal.org documentation is less gooder [sic] than what the rest of the internet has to offer. There are other topics that are also lacking quality documentation. You probably know what they are.

I know that Addison has amazing monthly challenges for the doc team, but here's mine: for every minute you've spent complaining about the docs in the last month, spend two minutes fixing the pages you think are confusing, lacking information or outright wrong. Did you write a tutorial in the last month on your own site because you couldn't find the information on drupal.org? Now's the time to make the d.o docs better--find the place where that information should be and add it. (Of course you should only add information that you have written.) Anyone with a drupal.org account is already a member of the documentation team and can add and modify documentation on Drupal.org. (Cool, eh?!)

If you have an awesome tutorial but you're not sure where it fits: ask! We're in IRC (#drupal-docs on freenode) and we have a mailing list. We can help you find the best spot to put the information. And if you can't find the best spot. At least find a spot. We have a list of recently updated pages and can shuffle new pages that seem out of place. The goal here isn't to have 9832878 variations of the same information in drupal.org, so look carefully and make sure you are adding new information before creating a new page. Chances are good the information is "sort of" there but needs a little bit of care to include the bits that are missing. This might mean you need to edit a couple of different pages to place all of your information into the site.

I know that it can sometimes be a little bit intimidating to edit The Official Documentation, but that's why we track revisions for the pages: so that you can make changes without worrying about losing information! If you've ever felt you needed an invitation or permission to edit the docs, please consider this a personal request from me to you. I need your help, the team needs your help and Drupal needs your help.

The multi site documentation

The multi site documentation updates are great - much clearer. Thanks!

Thanks for updating the

Thanks for updating the multi-site documentation! The improvements are great.

Of course you should only add information that you have written.

I have a different philosophy here. As somebody with an interest in documentation on drupal.org I've frequently found good documents that other people have written elsewhere. There are lots of great reasons for these to have been written and posted elsewhere. If I wait for the author to copy it to Drupal.org it will be a long wait. So sending the author a note and asking whether they would mind if you adapted it to the handbook style and included on Drupal.org.

It's also a great way to get started with doing some documentation for those who are interested in helping with the documentation. In this way we encourage people to both write helpful documentation, perhaps in ways that are more comfortable to them than doing it on drupal.org, and grow the community of folks working on documentation.

I agree. I am fairly new to

I agree. I am fairly new to Drupal, but have seen an instruction vital to implementing a module that is buried so deeply (and out of chronological, step-by-step order) that it is impossible to find except by accident. I've seen numerous posts asking how to get the module functioning. I intend to write some new and clear documentation once I'm done with my current project.

I also agree with Joshua above; if it's out there on the web, reach out and ask to use it! In responding to one of the "help me" posts on the Linkedin Drupal group, I started a discussion with another Drupal user who is also documenting the same module: we ended up scheduling a phone conference and sharing ideas. I will reach out to them to collaborate in combining efforts to create a solid guide for all users of this module.

I have to add this: when will Drupal implement separate search capability for the handbook, forums, issues, and project pages? That alone will make life so much easier for all of us. How much time is spent by the forum moderators and helpers answering similar questions? Their frustration is clear from the "do your research before posing (you lazy moron): now read this at www.alreadyanswered" type responses. If the split were made, those helping answer forum questions would have plenty of freed-up time and would probably help out with other documentation.

This topic infects every

This topic infects every Open Source project because many people prefer writing on their blogs or in similar places, like conference slides. Everyone has their own reasons and whether it's the lack of fame (official documentation entries are semi-anonymous), intimidation (dude, this example is like so insecure!), unwillingness to learn (docbook? like I want to learn docbook, and setup this seemingly impossible toolchain) or simply the thought didn't occur (what, me write official documentation? [normal] humans write this stuff?!) it's a worthy topic and I'm glad you're tackling it.

Sometimes I get frustrated and simply feel like openly stealing content and if someone asks just say "sue me" but know that's wrong. A related route is to read said tutorials several times, wait a day or three, then write related documentation. Of course the ideal route is asking the outside authors to write but "lack of time" is a common response.

Yes, I've grown more and more cynical over the years but am trying to lose that feeling. :) Having methods that deal with the above conditions (and human nature in general) is a good start.

It is boring work but it has

It is boring work but it has to be done so that there is not to much confusion in the future! Best regards, Huis Kopen

Drupal User's Guide

Drupal User's Guide

Site building for Drupal 7. Includes in-depth information on Drupal's most popular site building modules, SEO and accessibility. Two complete case studies are included in the book along with the tools you'll need to build (almost) any Web site with Drupal.

Available from Amazon.com.

Front End Drupal

Front End Drupal

The industry go-to for learning theming in Drupal 6. A great companion to Lullabot's book, Using Drupal.

Available from Amazon.com.

Twitter

Recent Tweets