Archive for the 'Writing' Category

Do you love the Web? Or at least like it a lot?

Do you enjoy teaching people how to make awesome stuff happen?

Do you have great writing skills and a knack for figuring out how stuff works by looking at the code?

Want to make the Web a better place for everybody?

If so, you’re in luck! Mozilla is now looking for a great writer to help make the documentation on the Mozilla Developer Center even better. Keeping up with the rapid pace of growth of Web technology is exciting and hectic, but extremely rewarding.

If you’d like to take a shot at making the Web better, maybe you should apply for our new Technical Writer: Developer Documentation position!

I’ve started using the whiteboard field in Bugzilla to take documentation-related notes about bugs, and I figured a quick explanation of what I’m doing would be helpful.

The “[doc-waiting-1.9.3]” note means that the issue isn’t expected to land until Gecko 1.9.3. This doesn’t necessarily mean it won’t be documented until then, it’s just to help me prioritize work, since for obvious reasons stuff that’s in Gecko 1.9.2 is my top priority right now.

“[doc-waiting-info]” is used so that I can easily see that I’ve already looked at an issue and have asked one or more questions that need to be answered before I can write the material up. This will help me avoid spending a lot of time looking at the same bug over and over again before I actually have the necessary information to write it up.

“[doc-waiting-landing]” is used to mark items that have a patch, but it’s unclear on which branch the code will be checked in (or if it will be at all). Again, this helps me avoid looking repeatedly at items that aren’t ready to write about yet.

I’m sure I’ll have more of these in the future, but I wanted to explain my usage of these in case any of them seemed confusing, and to point out that they don’t necessarily mean super-long delays getting stuff written about (especially in the “[doc-waiting-1.9.3]” case).

If you’re working on Gecko, or Firefox, or Thunderbird, or really anything in the Mozilla universe that may impact developer documentation, there are a couple of things you can do to ensure that the relevant changes to developer documentation take place.

I mention this periodically in several forums, but it can’t be said often enough, so here we go:

First, if there’s a bug related to your work, make sure the “dev-doc-needed” keyword is added to the bug in Bugzilla. It doesn’t matter if you’ve actually made the change or not. The writers only apply changes to the documentation once the bug is both tagged as “dev-doc-needed” and the bug is marked as fixed. Until then, we pretty much ignore it.

Second, make sure the change that impacts developers is clearly explained somewhere in the bug comments. If necessary, add a new comment that explains what’s changed and why it’s relevant to developers, or at least says “Comments X, Y, and Z are relevant to developers.” This will reduce the likelihood that we’ll have to hunt people down and ask a lot of questions in order to ensure that the stuff gets written up adequately.

Third, if there isn’t really a good bug in Bugzilla on what needs to be written, feel free to file a new bug against the Mozilla Developer Center’s Documentation Requests component, explaining what needs to be written up. Useful information here includes links to the files that have changed (especially IDL), multiple relevant bugs, etc.

In all cases, including information about who would best be able to answer questions about the topic would be extremely helpful.

You can pretty safely assume that if your material isn’t either tagged as “dev-doc-needed” or filed as a bug against MDC, it won’t get written about. The sooner either of these is done in the development cycle for a given release, the more likely you are to get good documentation written, because this helps me schedule writing work to ensure that there’s time allotted for everything.