New docs contributors may be afraid of moving too fast and breaking things – but don’t worry, you can’t. A simpler markup language and a robust community of experienced, multilingual contributors make it even easier to find what you love and dive right in.

Here are five key things you need to know about documentation but were probably afraid to ask. (If you have questions that aren’t covered here, just contact me.)

1. Docs are developed exactly like code.

If you’ve committed to OpenStack development in any way before, then you already know how to contribute to the docs project. All you need to do is clone the docs repo from https://git.openstack.org/openstack/openstack-manuals.git, find a bug to work on https://bugs.launchpad.net/openstack-manuals, and git, gerrit, and jenkins your way to becoming a documentation ATC! For all the gory details, head to https://wiki.openstack.org/wiki/Documentation/HowTo

2. Docs are now being written in reStructuredText (RST).

If learning Docbook XML scared you off from committing to docs before, those days are now behind you. We’re busy converting all the current documentation to RST, which is very similar to wiki markup. You’ll pick it up in no time! So far, the End User Guide and the Admin User Guide are in the new format, and for Liberty we intend to have the Installation Guide, Cloud Admin Guide, and the HA Guide converted as well. If you’re interested in helping out with the conversion to RST, or just want to find out how we’re going, all the details are here: https://wiki.openstack.org/wiki/Documentation/Migrate

3. Don’t worry, you can’t break things.

OK, if we’re honest, at is at least theoretically possible to break things. But you would need a lot of help. Docs have a great core review team that won’t allow anything stupid through the gate. So if you’re not sure of the best way to handle a change, or you just make a silly newbie mistake (we’ve all been there!), be assured that our experienced team members are there to answer questions, help you through your first patch, and — if all else fails — catch that patch before it gates.

4. We’re learning too. Ask us for help.

OpenStack is a big beast, with lots of moving parts, and while Documentation is only a small part of that huge machine, it’s still complicated enough on its own. No one person (even the PTL!) understands how all the pieces work in detail, and we’re all learning as we go along. So don’t be afraid to ask silly questions. And while we’re on the topic of asking questions, the documentation team comprises people from all kinds of technical and ethnic backgrounds, including many people for whom English is a second or even third language. Be clear and concise in your communication style, not just in the docs, but on IRC and the mailing list as well, and refrain from jokes that might not translate well. Be polite, be helpful, and we’ll all get the most of our community.

5. Finally, find something you really enjoy working on, and dive into it.

Then go beyond just patching and reviewing: attend meetings, have conversations on IRC and on the mailing list. Enjoy the community, just as we enjoy having you be a part of it.

Cover Photo by Anne // CC BY NC