Editors' Guide

Web Almanac editors are technical writers with a keen eye for content quality who help authors polish their final draft. Editors are tasked with ensuring readability and consistency across the Web Almanac rather than being subject matter experts in a particular topic. Those interested in reviewing for technical points should consider the Reviewer role instead.

• Commitment summary
  • How to join
• Copyediting
  • Meta
  • Non-technical
  • Technical
  • Suggested Process

Commitment summary

The editing process starts late in the chapter lifecycle. Authors and reviewers will first iterate on the chapter draft for technical correctness, then editors will iterate on it for content quality. This phase typically occurs in October-November.

There are 20+ chapters and, depending on their length, editing may take up to 2 hours each.

How to join

The 2021 project is underway and we're actively looking for editors! Browse the list of open chapters and comment in any chapter-specific issues that interest you.

Copyediting

The Google Developer Documentation Style Guide is an in-depth resource for technical writers. The Almanac will most closely follow 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

The general tone of the Almanac is "work fun", where we get into the weeds of statistics but try to make it fun and approachable for the average web developer without becoming too silly.

Meta

• When referring to the Web Almanac project, prefer "the Web Almanac" or "the Almanac" not "the almanac"
• Refer to the "HTTP Archive" as such, not "HttpArchive" or similar

Non-technical

• Prefer EN-US spelling throughout: "color" not "colour"
• Prefer oxford comma: "a, b, and c" not "a, b and c"
• Prefer past tense when referring to the analysis work: "we found that 25% of pages..."
• Prefer present tense when referring to the current state of the web: "...25% of pages make use of XYZ"
• Prefer plural tense (we) when speaking about the data analysis and the Web Almanac as a whole. Singular tense (I) can be used to indicate a personal (particularly controversial) opinion that is not backed by the data from the Web Almanac.

Technical

• Put a space between values and their units: "10 MB" not "10MB"
• Thousands are written as "10k" (lowercase for kilo and no space as part of number)
• Use two words for "web page" as opposed to "webpage", unless used in WebPageTest
• Use two words for "web server" as opposed to "webserver"
• Use one word for "website" as opposed to "web site"
• Use lowercase "web" and "internet", avoid "World Wide Web"
• It’s Jamstack not JAMstack, JAMStack or JAM stack
• Filename extensions should be avoided
• Use one word for "dataset" as opposed to "data set"

Suggested Process

• Open a new branch, and edit the Markdown for the chapter (NOT the HTML).
• Open the page (either in GitHub markdown or preferable by running the latest version of site as per the src/README.md).
• Copy and paste the body of the chapter into Word.
• Select the whole text and set Language to US English.
• Run a spell and grammar check, and make any necessary changes in Markdown.
• Do a global search any change smart quote to standard quotes for consistency ([“”] -> ", [‘’] -> ') - these will automatically be converted again on the site build point Authors to #1485 for any discussion on this
• Check all instances of "it's" to ensure they mean "it is", and if not it should be "its" without apostrophe. In fact I find it better to explicitly change this to "it is" where appropriate.
• Actually read the chapter now and make the edits.
• Split up large paragraphs.
• Split up long sentences.
• If it takes you several re-reads to understand a sentence/paragraph, then it is probably not clear. Reword.
• Authors may be used to writing for their area of expertise - the Almanac will likely attract readers from vary levels of expertise in each subject so bring it up a level. You may need to explain things that may be obvious to that particularly community (e.g. performance, security, SEO etc.) but are not to those less familiar with that.
• You can edit for conciseness, but be conscious that authors have spent considerably time on this and will likely question any large cuts. That's not to say they shouldn't be edited down.
• If in doubt on how a word is written, check out the word list.
• Acronyms should be written out in full first time they are used and be conscious of the table of contents generated for the chapter if it's full of acronyms, as that may be the first thing the reader sees.
• Check for common typos: javascript should be JavaScript, webpage should be web page, webserver should be web server, Brotli should be with capital B, Gzip should be capital G when talking about the format, lowercase g when talking about the verb (to gzip something), the file format and the program.
• Stylesheet is one we're going to use a different convention on. The style guide we use says it should be style sheet, with a space, but to me stylesheet is much more common (other than in the CSS name itself!). after discussion with the CSS authors in 2020 we settled on stylesheet without a space.
• Check for proper hyphenation of third-party and first-party: with hyphen for adjective (e.g. third-party performance, third-party assets) and without for noun ("The most popular third party is...").
• Try to avoid over-use of bold and even italics – Call out figures should be used for important stats, and italics should be used for introducing terms.
• Remove instances of "please" (e.g. "please refer to..."). See Politeness and use of please.
• Ensure the required meta data is at the top (check a 2019 chapter for what that is)
• Check headings - should start with an H2 introduction (## Introduction, and not ## Intro), as the chapter generator will add the H1 chapter title. All other headings should be H2 - H6. Look at the table of contents in generated version to ensure the headings are at correct level.
• Headings should be sentence case, that is only have first word, proper nouns and acronyms capitalized (e.g. ## How do cache TTLs compare to resource age?).
• Headings should have at least one sentence and not be empty (so called "Stacked headings", which are used to group headings but don't have any content themselves). "A heading is like a chapter title; it must have at least a sentence of information below it. Stacked headings can indicate inefficient organization of information."
• Ensure there is a Conclusion (## Conclusion) and ask Author for one if not, for consistency.
• Check internal links. They should be of the form [JavaScript](./javascript) chapter with a ./ reference, and the link should be on the chapter text itself but not the word "chapter". It is also acceptable to link related text (e.g. It is important for your website not to be [slow](./performance)). Make sure no trailing slashed in chapter text (e.g. ./performance/). Cross year links should be of the form in the [2019 JavaScript chapter](../2019/javascript). When referenced directly the chapter name should have an initial capital (For more information refer to the [Performance](./performance) chapter., but for indirect links it should be in lowercase (web [performance](./performance) is important). The same applied to links to the Methodology page (refer to our [methodology](./methodology) or refer to the [Methodology](./methodology) page)
• Check if more internal links could be added - it is good to reference the other Almanac pages.
• Check all external links work.
• Change all external links (except Wikipedia, MDN and Twitter) links to HTML format with hreflang (<a hreflang="en" href="https://...">...</a>) which then give styling on translations to show they are in English (Wikipedia and MDN are automatically handled based on URL, and Twitter offers auto translation so doesn't require this).
• Add links to specifications, blog posts, wikipedia for terms, complex subjects or where more reading can be done.
• Check if graphics look good. Refer to the Figures guides tip and advice.
• Consider adding some callout quote figures to break up long periods of text without graphics
• Check graphic numbering is correct in generated HTML
• Images should have descriptive names rather than fig5.png for example for SEO benefits and to allow for easier renumbering.
• Images and graphs should have figure markup as discussed in the Figures Guide.
• Figures should have very descriptive captions and descriptions.
• Captions should be in sentence case and end with a period or other punctuation mark like a question mark.
• Google Sheet gids and SQL links should be provided.
• Tables with numbers should be written in HTML (e.g. to allow use of class="numeric"). Make sure they match this example.
• Pay special attention to complex tables.
• Merge paragraphs into single lines - do not try to use newlines to format the markdown to avoid word wrap as too difficult to maintain with edits.
• Numbers less than ten should be written ("nine" not "9") except for percentages, or when part of a sentence already using numbers (e.g. don't write "six out of 15").
• Code format code and technical items (e.g. HTTP Header names - for example "The cache-control header...")
• Regenerate the chapter and repeat the Word spell check above (in a new Word document so any ignores are not ignored a second time).
• Ensure there are no inline styles (<p style="...">) - use classes instead to abide by our Content Security Policy.
• Use a Jinja comment starting with TODO so it's annotated in the markdown file, easily discoverable, and not included in the HTML output. For example: {# TODO: Link directly to the relevant Accessibility section. #}.
• Check previous years chapters table of contents and flag to authors if any missing pieces, to ensure they didn't accidentally leave out an important section.
• Check print version (add ?print to URL) to ensure all images load (check for console errors is the easiest way of checking this).
• Convert tables of numbers from markdown to markup with <td class="numeric"> to ensure that the numbers are right-aligned for legibility.
• Submit a PR with the author as a reviewer.
• Handle any linting or generation errors automatically on the PR.