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.
- 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
- Prefer EN-US spelling throughout: "color" not "colour"
- Prefer oxford comma: "a, b, and c" not "a, b and c"
- Put a space between values and their units: "10 MB" not "10MB"
- Use two words for "web page" as opposed to "webpage", unless used in WebPageTest
- Use lowercase "web" and "internet", avoid "world wide Web"
- Filename extensions should be avoided
- 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).
- 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 (“ -> ", ” -> ", ‘ -> ', ’ -> ')
- 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 see 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 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 they have the required meta data at the top (check a reviewed 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
./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.
- Check if more internal links could be added - it's 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.
<figure>tags around images with
<figure id="fig-2"> <a href="/static/images/2019/20_HTTP_2/ch20_fig2_http2_usage_by_request.png"> <img alt="Figure 2. HTTP/2 usage by request." aria-labelledby="fig2-caption" aria-describedby="fig2-description" src="/static/images/2019/20_HTTP_2/ch20_fig2_http2_usage_by_request.png" width="600" loading="lazy" /> </a> <div id="fig2-description" class="visually-hidden">Timeseries chart of HTTP/2 usage showing adoption at 55% for both desktop and mobile as of July 2019. The trend is growing steadily at about 15 points per year.</div> <figcaption id="fig2-caption">Figure 2. HTTP/2 usage by request. (Source: <a href="https://httparchive.org/reports/state-of-the-web#h2">HTTP Archive</a>)</figcaption> </figure>
Note the very description alt text, aria-labelledby and aria-describedby Note the image location is referenced twice - once to draw the image, and a second time to link to it when clicked so it can open the full sized image. Note that figcaptions should be in sentence case and end with a period or other punctuation mark like a question mark.
- Google embedded data sheets should be created with
<figure id="fig1"> <a href="/static/images/2019/07_Performance/fig1.png"> <img src="/static/images/2019/07_Performance/fig1.png" alt="Figure 1. Distribution of websites' fast, moderate, and slow FCP performance." aria-labelledby="fig1-caption" aria-describedby="fig1-description" width="600" data-width="600" data-height="371" data-seamless="" data-frameborder="0" data-scrolling="no" data-src="https://docs.google.com/spreadsheets/d/e/2PACX-1vSQlf3_ySLPB5322aTumUZhbVGdaUdkmi1Hs4bYuO3Z1kqM4xspx7REbwXukwPd_tsOSg6oImzpYLM9/pubchart?oid=115935793&format=interactive" loading="lazy" /> </a> <div id="fig1-description" class="visually-hidden">Distribution of 1,000 websites' fast, moderate, and slow FCP. The distribution of fast FCP appears to be linear from 100% to 0%.</div> <figcaption id="fig1-caption">Figure 1. Distribution of websites' fast, moderate, and slow FCP performance.</figcaption> </figure>
- Tables of data should also have have
<figcaption>tags, and no alt text is required:
<figure markdown> | CDN | Prioritizes Correctly? | Desktop | Mobile | Both | | ----------------- | -----------------------| ------- | ------ | ------ | | Not using CDN | Unknown | 57.81% | 60.41% | 59.21% | | Cloudflare | Pass | 23.15% | 21.77% | 22.40% | | Google | Fail | 6.67% | 7.11% | 6.90% | | Amazon CloudFront | Fail | 2.83% | 2.38% | 2.59% | | Fastly | Pass | 2.40% | 1.77% | 2.06% | | Akamai | Pass | 1.79% | 1.50% | 1.64% | | | Unknown | 1.32% | 1.58% | 1.46% | | WordPress | Pass | 1.12% | 0.99% | 1.05% | | Sucuri Firewall | Fail | 0.88% | 0.75% | 0.81% | | Incapsula | Fail | 0.39% | 0.34% | 0.36% | | Netlify | Fail | 0.23% | 0.15% | 0.19% | | OVH CDN | Unknown | 0.19% | 0.18% | 0.18% | <figcaption>Figure 14. HTTP/2 prioritization support in common CDNs.</figcaption> </figure>
- If tables are written in HTML (e.g. to allow use of
colspanand the like) then ensure headers use
- 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)
- Regenerate the chapter and repeat the Word SpellCheck above (in a new Word document so any ignores are not ignored a second time).
- Maybe use an HTML validator to spot any bugs in the code by copying and pasting the HTML. Not these can report errors that are nothing to do wiht the chapter markdown (compare to an already edited chapter to see the common templating issues).
- Submit a PR with the author as a reviewer