Editors' Guide

Editors' Guide

Web Almanac editors are technical writers with a keen eye for content quality who help authors polish their final draft.

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

Editing for the 2020 edition is still ongoing. Leave a comment on the Call for Editors issue to join the team. If you'd like to participate as an editor in 2021, fill out the 2021 interest form and select "Editor" as your team of interest. We'll be reaching out to everyone in mid-2021 when it's time to start planning the next edition.

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"

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 lowercase "web" and "internet", avoid "World Wide Web"
• It’s Jamstack not JAMstack, JAMStack or JAM stack
• Filename extensions should be avoided

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 (“ -> ", ” -> ", ‘ -> ', ’ -> ').
• 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 aboutn the formar, lowercase g when talking about the verb (to gzip something), the file format and the program.
• 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 biggest third party...").
• 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?).
• 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)
• Check if more internal links could be added - it is good to reference the other Almanac pages.
• Check all external links work.
• Add links to specifications, blog posts, wikipedia for terms, complex subjects or where more reading can be done.
• Check Graphics look good.
• 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, with optional plain text alt attributes.
• 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.
• If tables are written in HTML (e.g. to allow use of colspan and the like) then ensure headers use th tags, and add scope="row"/scope="col" attributes (especially for 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 ("ten" not "10") except for percentages.
• Code format code and technical items (e.g. HTTP Header names - for example "The cache-control header...")
• Regenerate the chapter and repeat the Word SpellCheck 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.
• Submit a PR with the author as a reviewer
• Handle any linting or generation errors automatically run on the PR.
• 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 messing 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