We are in the process of trying to use scrumbugs to track documentation from the point at which the bug is filed through prioritization, assignment to a writer, and eventual completion. This page will cover some details of how we use it.
Note: This is said several times throughout this document, but it bears special notice. We are just starting to implement this system, and not all of it is well-defined yet. In addition, there will almost certainly be changes as we learn what does and does not work well for us. We'll do our best to keep this article up to date.
Terms and values
The scrum "component" field ("c=" in the whiteboard on Bugzilla) should match the Bugzilla component for the bug, always. Scrumbugs should set this automatically if you don't specify this value.
The "user" field ("u=") should be one of the following:
- webdev
- The document will primarily be used by Web developers.
- mozdev
- The document will primarily be used by Mozilla platform or add-on developers.
- appdev
- The document will primarily be used by app developers.
- mdn
- The document is about MDN itself, such as docs processes.
The "points" field ("p=") is set to estimate how long it's expected to take to fix a bug, in terms of time spent working on the fix. If this is 0, the bug hasn't had a value assigned yet (so 0 doesn't mean "wow, that'll be easy!").
In typical scrum processes, these point values are generally used to represent a half-day or so of work apiece, but we'll settle into our own groove of how to use them over time (and will update this document once we do).
Lists and links
- Ready and in-progress bugs
- This page on scrumbu.gs lists our currently-in-progress bugs as well as those that have been triaged and are considered ready to take on.
- All open documentation requests
- This Bugzilla listing shows all open developer documentation requests, including those that have not yet been triaged.
- Submit a documentation request
- To submit a new documentation request, you can use this link.
Process
Every two weeks, we hold our MDN Community Meeting. During that meeting, we look over the backlog of bugs that are ready to take on and make suggestions for bugs that people could consider taking on. MDN staff writers will actually try to commit to specific ones, while other writers will simply be aimed at some within their interest or skill areas if they like.
Writers will take ownership of bugs by assigning the bugs to themselves. They should feel free to contact the appropriate developers if they need information (although at least making a solid attempt to figure it out for yourself will help you gain their respect, which goes a long way). You can often learn which developer to contact by either consulting the bug itself, in which we try to list the relevant experts, or by looking at the Subject-matter experts page here on MDN. If all else fails, visit #developers on irc.mozilla.org and ask.
Once you've claimed the bug, get to work! You'll find writer's guides and other useful information to help you get that part done here on MDN.
When you think you've finished updating the content, you should strongly consider setting the technical and/or editorial review flags on the article as appropriate, depending on the type of change you made. Whether or not this is necessary is to some extent a judgement call, since the amount of change and how likely it is you've made an error can vary wildly depending on how complex the change is or whether or not you worked closely with an expert to create the new or updated content. You should also consider actually asking the right person to look over your work; have an expert review your changes for technical errors, or ask for a spot-check of your writing of one of the other writers on #devmo.
Another way you can get someone to look at your work, if you find yourself otherwise unable to reach them, is to assign the bug over to them, adding a comment to the bug asking them politely to look it over. Be sure to mention what part or parts of the content you changed and what sorts of issues you're worried about, if any.
Once you're finished, and you feel good that your work is truly done and reasonably correct, go ahead and mark your bug as resolved/fixed! Congratulations!
See also
- The Developer Documentation project on Scrumbugs.