Feb 182014
 

A key aspect to the documentation process is communication. Not only is the completed documentation itself a form of communication, but thoughtful, helpful communication is critical to the production of documentation. For the MDN documentation team to create content, we need to be able to interact directly with the developers behind the technologies we write about.

Today I’d like to share with you how that communication works, and how you can help make documentation better through communication. Not only do we need your help to know what to document, but we need information about how your technology, API, or the like works. The less time and effort we have to put into digging up information, the sooner we can have documentation for your project, and the better the coverage will be.

Pro tip: Assume we know nothing about your project. We don’t know who you are, what your technology is or does, or even that it exists. If you start with that assumption, and provide all the information you have, everyone probably wins.

Share details

There is basic information we will almost always need when working on documentation for an API or technology. If you’re proactive about providing this information, it will save everyone time and energy. I mentioned this previously in my post about writing good documentation requests, but it bears repeating:

  • Who are the responsible developers? We will almost certainly have questions, and nothing slows down a writing project like spending two weeks trying to figure out who can answer simple questions.
  • Make sure we have links to the specifications and any design or implementation notes available for the project. We probably will find the specification on our own, but anything beyond that is likely to be missed. And if you send us the spec link (which you probably have memorized by now anyway), you’ll earn our appreciation, which can’t hurt, right?
  • Where’s the code for your implementation? Providing a link (or links) to the code tree(s) on mozilla-central and/or Github can save us tons of time, since we will refer to the code often while writing.
  • When the specification and/or design is finalized, let us know! We usually won’t start writing until the design has settled down into a reasonably stable state, and if we don’t know it’s stabilized, we might never get started. Similarly, if there’s an unexpected change after the specification was supposedly finished up, be sure to ping us then, too!
  • Do you have code samples or snippets? Sharing links to those, or to any tests you’ve written, can help us understand how your API or technology works—and it gives us a head start on writing example code for the documentation.
  • Do you have a schedule? Let us know when you expect to hit your milestones and when you expect to reach each branch.

Looping us in

The more your team is able to integrate the documentation team into your docs process (and vice-versa), the better. It’s actually pretty easy to make us feel at home with your team. The most important thing, of course, is to introduce your project to the writer(s) that will be working on documenting it.

To find out who will most likely be writing about your project or API, take a look at our topic drivers list on MDN. If you’re unable to figure it out from there, or don’t get a reply when you ping the person listed there, please feel free to ask me!

  • Invite us to attend any planning or status meetings for your project. Don’t assume we know about them (we probably don’t, unfortunately). Being able to listen in on your meetings (and occasionally even offer suggestions) is incredibly helpful for us. We see a lot of APIs, and you never know, we might have ideas you can run with.
  • Be sure we know what mailing list or mailing lists your team has discussions on. We will probably either want to become regular readers or at least be able to quickly pull up archives while doing research.
  • Let us know what IRC channels we should hang out in to participate in discussions about your project or the technology you’re working on.
  • Do you have work weeks? Invite us to join you! Having a writer attend your work week is a great opportunity to interact and get some face-to-face discussion in about the documentation, what you need, and what you’d like to see happen.
  • Whenever someone blogs about the project, technology, or API, let us know. Don’t assume we’ll see it go by on Planet, because odds are very good that we won’t. Ideally, you should add a link to it to your documentation request bug, but at least email us the link!

Join the conversation

We will almost certainly be having discussions about the documentation work you need from us! It’s often helpful for you to be proactive about being engaged in those discussions. It’s always best to get your input, requests, and suggestions sooner rather than later.

  • If your project is large enough, we might start having meetings specifically to discuss its documentation work. This type of meeting is typically short (our Web APIs documentation meeting has never run longer than 20 minutes, for example). We will invite you to attend these, and we’d love to have you, because it’s a great way for you to comment on documentation quality, priorities, and the like.
  • You’re welcome to join us in #mdn, the IRC channel in which we discuss documentation work, if you want to chat with us about specific documentation concerns or questions, or if you want to make a fix or addition yourself but need some advice.

Useful resources

There are a few additional useful resources on MDN that can help to improve the interaction between the writers and the developers for a project:

 Posted by at 12:44 PM