Volunteering for WordPress – Writing for the Codex

For the many months I’ve been overcoming my guilt over using WordPress for free by volunteering in the WordPress Forum and by editing and writing on the WordPress Codex, the official site for documentation on using WordPress. I thought I might tell you about it a bit.

While the WordPress Codex is based upon wiki, the open source, do-it-yourself, encyclopedia style software, the editors behind it have raised the bar on the “free for all” style wiki to make it a serious source of documentation for using WordPress. It started slowly, but it is growing like mad, stuffed with tremendous articles on how to use all the different features and functions of WordPress, from the very simple to the complex.

The people volunteering on the project, helping to develop and write, edit and fix all the documentation, are serious about what they are doing. Not so serious as to not welcome every one who contributes, but serious about making sure the documentation is RIGHT. Everyone checks everyone’s work, as much as they can, to keep the grammar and spelling right, but also to make sure every bit of code is right and works. Sure, it’s all volunteer work and there are slips of the hinger on occasion, but everyone strives to make sure that the WordPress user of any level has access to the documents they need to understand a particular feature or function.

Hanging Around the WordPress Codex

I test drove WordPress for a couple of months, and then decided to convert my entire site over, a major undertaking. There was so little I knew and so much that I had to learn, I decided that I would start hanging around the WordPress Codex to read what there was to read and to learn more. Unfortunately, my second document featured the word “seperete” over and over and over, throughout the entire document, until I wanted to scream. I did some checking and found out that anyone could edit the Codex. So I went in and fixed every one of those missed-spellings to “separate”.

Over the next few weeks in my spare time at lunch and late in the evenings, I started fixing more and more. Slowly I got the hang of it. Then someone told me that I needed to make a User Page for myself. I read up on it and did so, and now I had a page of my own on the Codex. For what, who knows, but at least if I really screwed things up, the editors now had a place to leave me a message.

As I came to understand more about how WordPress worked, I started asking questions, clarifying the documentation. I was using the Codex for technical support, but I knew I had to go to the Forum for true support. I approached it as “if I don’t understand what you are saying because I’m a newbie, then other newbies won’t understand either, so let’s fix this.”

I then signed up for the mailing list of the Codex volunteers. This is the email list where people talk about what they want to do and where the Codex is going and get their questions answered regarding their work on the documentation. During one of those chats, it was clear that there needed to be a document specifically for new users, one that would hold their hand, introduce them to the terms, and link to all of the technical articles in the Codex. Since I’m as new as they come, I volunteered.

First Steps With WordPress was born. It was a chatty style document that offers step-by-step instructions on how to spend your first few hours with your newborn WordPress site. It peels back the layers so we discover how it works together. That got high praise, and high praise encourages more work…so things started snowballing.

Then came the long awaited release of WordPress version 1.5 and the Forums were filled with users struggling to upgrade to this dramatically improved version. Almost everything changed with 1.5 from the codes to the way the presentation of a WordPress site was styled with Themes. Now familiar with the Codex, I didn’t have the knowledge to really help some of those people, but I knew what documents might help them, so I started posting links to the documents on the forum.

I was surprised that so few people even knew there was such a documentation site. Visits to the Codex started increasing and people were welcoming this new access to information.

Then The WordPress Codex Broke

It was one week into the release of version 1.5 and the main documentation site was down and the developer was at a conference, unable to be reached for four days.

People were desperate for help and the Forum volunteers were working overtime to help them, but many of those hadn’t installed the new version themselves, so they did the best they could. I wanted to help, so behind the scenes I talked to a few of the volunteers and decided to start WordPress Lessons on the Forum to bring the Codex to the Forum. I started with a couple of Lessons on styling and layout, because many people were faced with the challenges of styling their new WordPress sites. This is something I know a lot about, so I could help here.

I made a big announcement, with instructions on what a “Lesson” entailed and how to post it, and then we started a list of what needed to be written about. I posted my little lessons on CSS and others started jumping in. Before we knew it, we had five, then six, soon a dozen different lessons within that weekend to help educate people and make up for the breakdown of the Codex site.

WordPress Lessons

Like many things I do by starting out naively and boldly going forth, the idea of WordPress Lessons took off. I had offers to turn these into an independent website stuffed with tips for the WordPress user, and people who wanted to turn these into articles on their site. I gave it some thought and realized that these were meant for the Codex.

It’s important to WordPress to have everything under the same umbrella. Already people were starting their own WordPress named sites for Themes, Plugins, and tips. I saw the future and the future is unity not scattered diversity. I said no.

I then talked to the editors/documentation team for the Codex about turning these into lessons for the beginner users of WordPress. I would take my postings on the Forum, along with other people’s comments, tips and advice along the various Lesson threads, and turn these into documents.

With the help of Carthik, one of the leading editors of the Codex, and many others, I created WordPress Lessons. People loved them. Now there was documentation for the novice. Soon, others wanted to write articles for the Lessons, but I realized that these needed to be written differently from the rest of the Codex, so I wrote up guidelines for the new articles.

Basically, writing technical documentation means writing command sentences. Do this. Do that. Open this. Close that. There is no you nor I in these technical documents. And there shouldn’t be. But when it comes to hand-holding, to writing documentation that helps the beginner go through the process, it has to be friendlier. “You put this here”, “you can type in”, “go to your folder”, and more third person references. There is no “I” when writing these things either, as they aren’t editorial articles, either, that ramble on about how “I did this” and “I did that”. It’s about the “you”, the beginner, and “I” the writer is talking to you, showing you and telling you how it should be done.

It also opened up the Codex in an amazing way. Instead of stuffed with technical how-tos, these boring technical documents could now be linked to from a friendly face that said, “hey, this is how you do it, step by step, and if you want to know more, check this out”. With articles like Stepping into Template Tags, using template tags in WordPress wasn’t terrifying or overwhelming any more. Template tags had a friendly face in addition to their technical face.

It also created expertise levels. Beginners had a set of documents to ease them into the harder subjects, and the intermediate and advanced users could go right to the core subjects and skip the hand-holding.

Volunteering on the WordPress Codex

I now can write some code and can look at PHP and not cringe or blink mindlessly, thanks to the WordPress Codex. If you have any writing or editing skills, or you want to contribute to WordPress and you don’t have the time nor skills for development work or answering questions on the Forum, join us on the WordPress Codex.

There is an article with information on how to get involved in the Codex, and there are a lot of things to do. Like all volunteer projects, people come and go as they have time. Everyone contributes in some way.

There are some fun things and events going on, too. We’re getting ready for a Codex Cleanup Week, a 9 day period in June where we encourage people to get in and get their hands dirty cleaning up the documentation and adding to it. There are also events coming soon which coordinate activities on the Forum and in the Codex. Soon, the look of the Codex will also be overhauled to resemble the rest of the WordPress official sites.

In general, we need people to help a little or a lot. We need people to take on the responsibility of a section or activity. For instance, we now have a “greeter” just like WalMart. This person’s responsibility is to welcome all new users to the Codex. For a few minutes during his day, this person checks the Recent Changes page and notices any new Users or User Pages. He visits and posts a “welcome” message on the page, welcoming them to the WordPress Codex and giving them basic information for volunteering and contributing to the Codex. It’s a small job but critically important. We have a lot more like that, and even bigger jobs.

If you have an article to share on using WordPress, or you just want to give back, check out the WordPress Codex and see how you can help the WordPress Community.