By arianek on

With Drupal 7 down to 30 critical bugs, and Drupalcon Copenhagen just around the corner, it's only a matter of time before Drupal 7.0 ships. We want to make sure our Drupal 7 documentation is in great shape for this fantastic new release, and the Documentation Team could really use YOUR help getting there!

What's done so far

We had some awesome people step up to help with updating the Help pages in Drupal 7 over the winter. Since then, Jennifer Hodgdon (jhodgdon) from Poplarware, Lee Hunter (leehunter) who's a technical editor for a Canadian government agency, and myself (arianek) have been doing our best to keep things rolling along, but we definitely need more people helping out to keep the documentation up to date with all the development that's going on.

We've made some decent progress on updating core module pages, and reviewing the install guide and upgrade guide (thank you to the few who've been able to help!), but there is still lots to do.

Who's managing what

API documentation: Jennifer has been managing mainly the API and in-code docs (issue queue) and they're in decent shape at this point, but if you're a coder looking to help with docs, that's definitely the place to go (and the person to contact).

Handbook structure: Lee has been focusing on trying to clean up and reorganize the online Handbooks, as well as helping out with updating core Handbook docs for Drupal 7. If you have questions about where to find a section of the handbook, or a particular page's placement, contact Lee!

Drupal 7 Handbook updates and general management: I've been focusing on updating core docs for Drupal 7, and managing and addressing smaller issues in the main Docs issue queue (for the online docs).

Not only could we use a hand keeping up with the general day to day issues in the main docs queue, but we definitely need a good charge at getting the Drupal 7 core docs updated (never mind all the various contrib docs). As the developers are madly working to launch Drupal 7, we're playing catch up with the docs, and need to get ready to help new or existing Drupal users make the upgrade.

If any of these areas sound like something you're interested in helping with, please track us down! We can't do this all by ourselves, we need your help!

How you can help with Drupal 7 Docs

Jennifer and I have been maintaining a high priority to-do page just so that you can see both the main Handbook and API needs at a glance. But as far as the online docs go, there are only 15 important but fairly easy to address critical issues left to close for Drupal 7 core docs.

Not all of these need a high technical skill level (though it doesn't hurt); mainly all you need to be able to do is install Drupal 7 somewhere and review whether the current docs match or note what's missing, and then comment on the according issue. Better yet, you can make edits right to the docs page (aside from a few that only Docs Admins can access), and then post a comment on the issue for someone to review your revisions.

For instance, updating the core modules pages is more of a time consuming than challenging task, while writing the pages for entirely new modules is a bit more challenging, as many have no existing docs outside of the Help hook in the module.

Basically all of this needs to get done, and every little bit helps! The main install guide issue is really close to being closable, just needs another review and we can mark it fixed.

What's in it for you?

Massive Drupal karma!!! Not enough motivation?

Contributing to Drupal Docs is a fantastic way to learn more about how specific parts of Drupal works (you have to spend time learning so that you can document). Not only that, but as an absolute beginner, this is a quick way to get mentoring from some of the brightest core contributors around. 

As an Open Source project, everyone needs to do their part; there is no "they" when you think to yourself "I wish they'd write some better docs for that". They is YOU! Most of us make our living using this free software and building things with it, so it's important to set aside time to help build, test, and document as much as you can!

Did I mention it's fun? Ok, maybe it takes a certain type of person to enjoy writing technical documentation, but I love it and have made great friends and connections through this work. I actually find it sort of soothing working on the Handbooks when I can squeeze it in (which is not often enough these days)...yes, really, all that nice structured consistently styled text!

Need help getting started? Want to contribute to Docs in a more general sense?

⋅ Categories: Drupal 7.x

Comments

gdd’s picture

gdd
he/him
Primary language English
Location Portland, OR
commented

I have been involved in several documentation efforts this year, and there is one thing that inevitably came out of these efforts - I found bugs in code and they got fixed. You see, when you write documentation, you are forced to take a bit of code and really understand it. You pre through it, make sure it does what you're saying it does, and test it. Guess what happens when you dig into code that deeply? You find bugs! Usually they are small or subtle. A misnamed variable, a branch that can never actually get reached, an improperly written test, an unclear or difficult to read statement. However the more bugs of this type that are found, the less user frustration later in the release cycle, and the less support that has to happen after Drupal 7 finally gets out the door. I would say that the ratio of my docs patches to bug fixes resulting from docs patches is on the order of 1:1.5.

If you are interested in getting involved in core, working the docs queue is the single best way to do it. You find bugs other people miss, the patches are generally easy to get committed, you get used to the issue queue and creating patches, and best of all the patches are enormously valuable. Get to it!

arianek’s picture

arianek commented

It's so true, Docs is both an excellent way to poke holes in things, and learn a ton! It's also an amazing way to get mentoring from super awesome developers!!! I am shocked more people don't jump at the opportunity. ( <-Not supposed to sound sarcastic!)

skyredwang’s picture

skyredwang
Location Shanghai
commented

When you play with D7 or D7 API, at first time testing, try not use docs when it's possible, so you don't follow the logic/mind flow of the people who wrote them. You might be surprised that how quickly you can find bugs and make suggestions. Then document what you found.

peterx’s picture

peterx commented

One problem that hits the documentation during a restructure is the problem of finding those pages you found last month and want to use now. If I have a bookmark, everything is fine because the node is constant. If I do not have the node bookmarked, I look through the menus for titles but titles often change during a restructure. The page might move to a completely different section. If a page is moved and renamed, it would be nice to find the page by the old title.

How can we do that? Probably the easiest way is to leave a link on the old parent page. Something like:
"How to create a new node type from your code" is now titled "Creating a content type in your module" and has moved to ...

Tags help but finding something can be a pain if you do not know what tags are in use. Perhaps the previous example could be something like:
"How to create a new node type from your code" has moved and is now titled "Creating a content type in your module". That and similar pages are tagged:
module
custom content type

One thing that is useful, particularly for module development where it is different, is to put a link from the Drupal 6 page to the Drupal 7 equivalent.

petermoulding.com/web_architect

wabs’s picture

wabs commented

Mentioning 30 critical bugs might have been a curse, as they have been going up and down since then, but on average stayed around 30 all the time since this post...