Reviewers' Guide
Reviewers are responsible for reading over authors' chapters and providing technical feedback on the contents of the reports as well as ensuring that the writing style conforms to these general principles. We also encourage reviewers to get involved earlier to review the scope of the chapter and metrics involved so important analysis is not identified after it is too late to be included.
Note, while reviewers will naturally pick up and point out some readability issues (and that's good!), their focus should be on the technical accuracy of the report. We have a separate Editor's role which will review the report for readability and consistency across the Web Almanac. We'd prefer the Authors and Reviewers concentrated on the writing, rather than worrying about these aspects initially.
If you're considering becoming a peer reviewer of a Web Almanac chapter, you're probably wondering what the level of commitment is. Reviewers' responsibilities may vary depending on the complexity of the topic and the total number of reviewers. Generally though, you should expect to spend your time in the following way:
- Content planning: about 4 hours working with authors and other peer reviewers to brainstorm the scope of the chapter and what stats/metrics are needed from the HTTP Archive dataset. The planning phase may vary year to year but will typically occur during May-June.
- Data validation: about 1 hour working with authors and data analysts to validate that the results pulled from the dataset align with your expectations. This phase is meant to catch analysis bugs early so we can rerun queries and ensure that your chapter is methodologically valid. This phase typically occurs in August-September.
- Content writing: about 15 hours working with authors to revise the contents of the chapter for technical correctness. This phase typically occurs in October-November.
The total commitment is approximately 20 hours of work over 6 months.
The 2021 project is underway and we're actively looking for reviewers! Browse the list of open chapters and comment in any chapter-specific issues that interest you.
The Google Developer Documentation Style Guide is an in-depth resource for technical writers. Familiarize yourselves with the "General principles" section, specifically:
- style-guide highlights (if nothing else, read this!)
- style and tone
- accessible content
- writing for a global audience
- writing inclusive documentation
If all chapter authors and reviewers follow these guidelines, the Almanac will have a consistent style and unified voice.