Finding someone who is not only expert enough but has the time to and is willing to help by performing a technical review of content you've created or updated can be tricky. Even once you find the right person for the job, getting them to make time in their busy schedule for a technical review—which may not be a priority for them—can sometimes require finesse. This guide will help you find the right person for the job, then convince them to help.
Once you've finished writing or updating an article following the various guidelines we provide, you may feel that a technical review is needed. Below, we'll look both at tips for deciding when to request a technical review and how to find and recruit a reviewer.
When to request a technical review
When should you request a technical review? If one or more of the following statements are true, then you probably should get a technical review:
- You've added significant amounts of new material, such as documentation for new interfaces, methods, or properties.
- You've updated content based on a bug or specification which you're not certain you've interpreted correctly.
- You've written a tutorial or sample code which should be reviewed to ensure that your implementation follows best practices as understood the experts.
- You're concerned that you may have made mistakes, or misinterpreted the subject matter; or, the subject is complicated enough or important enough that a review is needed to be confident that the content is correct.
Of course, this isn't an exclusive list! You should request a review any time you feel it to be necessary. Even if you just think it might be necessary, it doesn't hurt to ask. And if you're just not sure if a review is needed, feel free to drop into the #mdn channel on IRC and ask for a second (or third, or fourth) opinion.
Before requesting a review
Before you request a review, there are a few things you should think about so you can determine how to proceed:
- How urgent is the review? Is the material about a "hot" topic, such as something expected to be a commonly-used technology, or one which will be heavily discussed on blogs and social media?
- How likely is it that you've made significant mistakes (meaning mistakes which could confuse or mislead readers)?
- How long will the review take to complete? This depends both on the complexity of the topic and the amount of material that needs to be reviewed. And if there's sample code, that will take even longer to review.
You want to both know how hard to push to get a review done, but also have information about how much time the reviewer will need to set aside to do the work. Having that information, and providing it when requesting the review, will go a long way toward helping you get the help you need.
Recruiting a reviewer
Once you've finished writing and are ready for a technical review, make sure the "Technical Review Requested" flag is set on every page that needs to be reviewed. Now it's time to ask for the review. There are several ways to find someone to get a review; typically, you should start with the first one and work your way down the list if you fail to find someone to do the review.
- Start by posting a comment in the bug asking for someone to do a technical review. List all the changed pages and sections of pages, complete with links. The easier it is to find the stuff that needs reviewing, the more likely you are to get a review. If you can see who the most likely candidate is, use Bugzilla's "Need more information" option (commonly referred to as "needinfo" or "NI") to get their attention.
- If that doesn't get any action in a reasonable amount of time (at least an "I'll do it in a couple days" comment within a day or two, depending on the urgency) follow up by directly emailing the person or people that contributed the patch(es).
- If that doesn't work, follow up by asking in the appropriate IRC channel. Say something like "Hi everyone. We've got new/updated docs for X, and could really use someone who knows X well to read it over and make sure we got it right. Check out bug X, comment Y <link> for a list of what needs looking at. Anyone able to help?"
- If that doesn't work, that's when you politely send email to ask the manager of the team responsible for the technology in question to suggest someone to do the review. "Hi ManagerNameHere! We just finished documenting X and could use a review. Do you know who would be a good person to read it over and let us know where I got things wrong? Thanks so much in advance!"
- If that fails to get a suitable answer, that's when the decision needs to be made: how urgent is the review? If you feel that the odds of significant technical mistakes is low and/or the technology isn't a big one that lots of people will need or use, then you can probably let things go for a while and let reviews naturally happen a bit at a time.
- If the odds of a serious mistake are higher and/or the tech is a key one, then you should escalate the review request to an MDN administrator (Jean-Yves, Sheppy, Will, Florian, Jérémie, etc) and see if they agree that it's urgent; if they do, they can attempt to encourage someone to take on the review, or find a manager to prod someone into action. Ask on the #mdn channel for help making this happen.
Writing the request
Be sure to include in the request for review a link to the article How to do a technical review, so the reviewer can find the information they need quickly and easily. You should also, of course, provide a list of links to all the pages that changed (including section names, if appropriate). The more information you provide about what you've done and what you expect of the reviewer, the more liekly you are to get a satisfactory review.