Drupal is an ever-changing landscape, so it happens fairly often that you come upon a challenge you've never had to do before. Perhaps it's adding Views integration for a contributed module. Maybe it's trying to figure out how the heck to CCK works internally. Or possibly you've been tasked with adding recurring billing to an Ubercart store. These are all challenges I've run across in my day job and needed to figure out.
Whatever the challenge, you're going to have to dive in and figure out how some module or feature works. This usually is some combination of playing around and, when that fails, reading the documentation. And, because Drupal is a largely volunteer-driven open source community, you might find that documentation to be... sub-par (or even non-existent).
What to do? Well, here are some options...
The Loner
Spend the next several hours smashing your face into a wall figuring out how the darn thing works. Curse and spit at Drupal, at the module maintainer, at the world! Fix your problem, then move on with your life.
This "works", for some values of works. We've all been there. But it does nothing to improve the situation for the next poor schmuck who comes along and has to repeat the process. The community's collective hours spent on face-smashing tends to grow exponentially the more popular and less documented a project is. Everyone loses.
The Hater
Take your aforementioned cursing and spitting about the lack of documentation to an irate blog post or the developer's issue queue. Make sure they know how totally unacceptable the state of their documentation is and demand that they fix the situation.
This doesn't tend to go over well at all. Realize that from the module developer's standpoint, you're yelling at them about code that you just got for free and that they spent an enormous amount of their own personal (and in most cases unpaid) time on. You're likely to end up with a frowny face against you karma-wise which makes people far less willing to help you in the future. This is bad, especially in a project with as much "tribal knowledge" as Drupal.
The Doer
Write the documentation that's missing yourself, as you figure it out. You have to figure it out anyway, so why not? By writing it down for others, you both cement the knowledge in your head since you have to "teach" it, and you also do your Drupal karma good deed to help the next person not have to struggle as much as you did. And If karma isn't a powerful enough incentive, remember that the next person might be you again, six months from now. ;)
And often, module maintainers are willing to bend over backwards to help you if you're willing to help with documentation. It's win-win-win!
"But I don't know what I'm doing yet!"
Perfect! You are at exactly the right spot in your learning curve to write and fix documentation! Why? Because you know what someone in your shoes finds confusing!
If the module developer writes documentation, it's probably going to end up something like this:
Backreference Module provides a nodeapi interface to maintain 1-1 relationships between all shared instances of a nodereference field. This means that given a field instance of field_reference1, if you add a reference to NodeBeta to NodeAlpha's field_reference1 and NodeBeta has an instance of field_reference1, then NodeAlpha will be added to NodeBeta's instance of field_reference1.
If you write documentation, coming into this project fresh, it's probably going to end up something more like this:
BackReference module maintains one-to-one relationships between node reference fields.
For example, let's say you have two content types: Attendee and Event. Event has a node reference field called "Attendees" (field_attendees) that references Attendee types. When you click on an Event node, you'll see a list of the Attendee nodes that it references; this functionality is built into the core CCK Node Reference field.
BackReference module allows you to have the inverse, where clicking on an Attendee node will show you the Events they are attending.
If you're not sure about something, take a stab and label it with something like "TODO: Is this right?" Someone else can always come along after you and edit your docs to fill in the holes. But laying out the map of what holes need to be filled is something actually best achieved by people who don't understand how things work yet, because they know the right questions to ask.
Ok, fine. So where do I start?
Documentation usually comes in the following forms:
- Basic documentation: Stuff like README.txt and INSTALL.txt that explain how to get the module up and running. These are generally improved by patches in the module's issue queue. Don't know how to patch? Just paste in some text into an issue. Lots of other people know how to make patches out of it. (http://drupal.org/patch has the full skinny if you're curious; it's a great skill to pick up!)
-
Handbook documentation: For more comprehensive documentation, often modules will have their own set of dedicated handbook pages. Look for a "View documentation" link on the project page. Almost all handbook pages can be edited by anyone with a Drupal.org account, so fill your boots! If there isn't already a handbook page, go ahead and browse around sections like the Administration guide or Site building guide and create a new page for the module in the most appropriate spot (if you don't know, just pick the closest match you can find; it can always be moved later).
File an issue in the module's issue queue (or general Documentation queue for "meta" handbook pages) that indicates what you're working on and link over to your stuff for review.
- API documentation: For programmers, it's really useful to have salient and relevant API documentation for a given project. The general convention on API docs is to create a project.api.php file that explains how the various hooks it exposes functions. If a module has one already, file a patch in the issue queue to clean it up. If not, create one and attach it to a new issue.
- Crowd-sourcing: If you're working on some docs, make it a community affair! Hop on IRC / Twitter and announce to everyone that you're working on documentation for X, and see if you can wrangle a few other people to help using a real-time editor such as Etherpad. We did this the other week with Panels 3 documentation and it was a blast!
New to the drupal.org issue queue? Check out Addi's helpful issue queue tutorial video.
For more "real-time" help on where to put docs, how to use the issue queue, and so on, hop onto IRC: irc.freenode.net, channel #drupal-contribute.
New to IRC? Check out the docs on Drupal.org: http://drupal.org/irc
So let's do it!
So don't be a loner. Drupal has a huge community of people who absolutely love to help people who help others; there's no reason to go it alone!
And don't be a hater. In addition to making life generally miserable for those around you, this has real consequences for you when you find yourself in need of help later.
Instead, do it! Let's get out there and clean up some docs! :)