Section Coordinators' Guide
Section Coordinators are project managers who are responsible for the progress of all chapters in each of the four main sections of the report: page content, user experience, content publishing, and content delivery. Section Coordinators work closely with Authors and specifically the content team leads to help guide them through the process and ensure that their chapters are progressing on schedule.
The level of effort may vary for Section Coordinators depending on the number and complexity of chapters in their section. Some sections may require more than one lead. If you're interested in becoming a Section Coordinator, you should expect to spend your time regularly checking in with content teams on GitHub, Google Docs, Google Sheets, and Slack to make sure that they're unblocked and making progress.
The total commitment is approximately 40 hours of work over 6 months.
- Recruiting contributors (authors, reviewers, analysts, editors) to staff each chapter
- Selecting lead authors
- Setting expectations on due dates and milestones
- Meeting regularly with content teams to keep on schedule
- Ensuring chapter outlines are appropriately scoped
- Reviewing chapter drafts for content quality
This section describes everything a new coordinator would need to know to get up and running.
When a new project starts at the beginning of the year, the Editor-in-Chief (Rick) will create the table of contents of all chapters and their respective top-level sections. This list is shared as a public post to kick off the new project. Each section coordinator will be responsible for the chapters within their section. Large sections may have multiple coordinators as needed.
GitHub issues will be created for each chapter, where contributors can volunteer for specific roles like author, reviewer, analyst, or editor. The responsibility of the section coordinator is to shepherd contributors to the appropriate roles by clarifying the duties and expectations. For a chapter to meet the first milestone, it must have at least one author, reviewer, and analyst. So it's critical that we prioritize filling out the team as quickly as possible. This gives teams a head start to work on the content outline. For that reason it's also less important to fill the editor role since they are not needed until the writing begins in the middle of the project.
As contributors leave comments to join the team, coordinators should be adding them to the project's team in the HTTP Archive organization on GitHub. For example, the 2022 Web Almanac team consists of everyone who wants to contribute. Adding contributors to the team will give them write access to the Web Almanac repository, which is necessary for keeping the chapter metadata up to date. It also allows us to assign issues and PRs to contributors as needed. Another benefit is that we can broadcast messages to everyone on the team, like weekly project updates that are applicable to everyone.
Coordinators should be team maintainers with the ability to add new members. Team members will have a "Member" badge next to the emoji selector in their comments. Note that contributors who are returning from a previous project will still have the badge even if they're not necessarily a member of the current year's project. Add them to the team so they can still receive project broadcasts. For all other new contributors, they actually receive an invitation that they need to accept before joining. If a contributor does not accept, the invitation may expire and need to be resent. Contributors with pending invitations can accept by visiting https://github.com/HTTPArchive, where there should be a prompt to accept.
Analysts need special access to the HTTP Archive project on GCP in order to query the dataset without personally incurring any costs. Coordinators should chat with each analyst to get the email address they'll use to access BigQuery and pass those off to Rick or someone with the ability to add members to the GCP project.
If a chapter has only one prospective author, they are the de facto content team lead. Most of the time, though, multiple people are interested in authoring the chapter, so we need to pick one to be the lead. That decision is up to the EiC, with input from the coordinator.
Before settling on the content team lead, coordinators should verify with the prospective author that they can commit to the additional management responsibilities. When leads are finally chosen, coordinators should clarify the expectations of the role and what the next steps are to keep the chapter on schedule. Coordinators are encouraged to set up a meeting with content team leads to kick off the project and answer any questions in a high bandwidth channel.
The immediate next step for anyone joining the content team is to start planning the contents. To do that, coordinators should direct contributors to the shared team resources that are linked in the chapter issue. Contributors must request edit access to the doc in order to add ideas. Each chapter also has a channel on Slack where contributors can collaborate throughout the project. Coordinators should ping contributors as needed to make sure they're aware of what to do next.
Content team leads are responsible for keeping their chapter's metadata up to date. All of this is maintained in the chapter's GitHub issue and includes: the list of milestone checkboxes, the content team table of members and roles, and the "help wanted" labels.
The milestone checklist and content team table are consumed by a GitHub action that automatically runs whenever an issue is edited and updates an issue that provides an overview of all chapters' progress (2022 for example). This helps us keep all chapters on schedule and adequately staffed. So it's important for team leads to update their metadata when progress is made so that it's reflected in this tracker.
Before a chapter has a team lead, the coordinator should be keeping the metadata up to date. When a team lead is chosen, they should be told about this process and reminded as needed.
The other part of the chapter metadata is the "help wanted" labels, which signify that specific roles still need to be filled: coauthors, reviewers, or analysts. We can create a hostlist of all chapters that need a particular role filled and share that with prospective contributors to more easily find a team to join. As roles are filled, team leads should remove these labels.
Coordinators are also liaisons between past and present content teams. Coordinators could ping previous years' content teams to make sure they're aware that the call for contributors is open and try to fill open roles. Unless they've shown interest this year, try to only ping them only once.
You and/or members of the content team are also encouraged to use social media to attract new contributors. Also consider posting the opportunity in common interest groups related to the chapter, for example you can reach out to the WordPress community to staff the CMS chapter. Keep in mind that this might introduce a bias in the content team if they all represented one entity, so consider also reaching out to secondary groups.
Generally, coordinators should look for signs of stagnation and make sure that teams have the resources they need to keep making progress.
Content teams don't need to wait until the team is fully formed to start planning the content. Brainstorming can happen when there's only one contributor on the team. Teams should be brainstorming content in the chapter outline section of their shared doc. We're looking for a high-level table of contents for the chapter that sets the scope of the topics covered. It's common to start with the previous year's published TOC and iterate from there.
Coordinators are the primary reviewers for chapters' outlines and content teams should have the coordinator's LGTM before marking the content planning milestone complete.
Coordinators should look out for signs that the outline may not meet our content quality bar. Content should have a data-driven narrative to explore the state of the web. It's not our goal to write tutorials about how to use a particular technology, we're more interested in its adoption and how it's already being used by the community. Content should also have a sufficient amount of depth to it. If a chapter only consists of one or two metrics, that's a strong signal that it would be better off merging with another chapter or dropped entirely.
While the Web Almanac is a project of the HTTP Archive, we don't necessarily need to rely solely on data from the HTTP Archive. The Chrome UX Report is commonly sourced in Web Almanac queries for real UX data. Other public data sources may be used, but we strongly prefer in-house data whenever possible. If not, the data should come from a trusted source and it would ideally have a transparent methodology of their own, in keeping with our data integrity standards.
Authors, reviewers, and analysts should use the planning phase to enumerate each metric that they'll need to substantiate the major topics in the outline. Analysts can refer to past years' queries for inspiration, but often new queries will need to be written.
In order to stay on schedule with a rapid timeline, analysts are strongly encouraged to start drafting their queries during the planning phase, rather than waiting for the Almanac crawl to finish. The project leads are responsible for generating the data needed for the almanac dataset on BigQuery and can populate it with sample data from an earlier crawl to facilitate earlier analysis.
A significant benefit of drafting queries this early is that it exposes limitations. If a query is simply infeasible for methodological reasons, the content team can work around it accordingly. If a query requires a new custom metric, which are executed at runtime for each test, the analyst (or someone else on the content team) has time to implement it before the Almanac crawl begins.
Analysis takes a long time, so starting it early should be a very high priority. Analysts should draft their queries as soon as possible. Once the Almanac crawl is completed, they can update their queries to point to that dataset, execute them, and save the results for the content team to start processing.
Coordinators are expected to check in with content team leads to ensure that they're aware of this process and working with their analysts to stay on top of any necessary prep work.
Reach out to rick@httparchive.org if you're interested!