Technical accomplishments
The Web Almanac Development team does more than just build a simple website to host the Almanac, and in fact they have built some pretty amazing things.
We aim to use the best of technology available to lead by example to showcase what is possible on the web. We want the Web Almanac to illustrate many of the suggestions and recommendations discussed in the chapters and with the code fully open sourced and available on our GitHub repository, it can serve as a good example for implementing many exciting new features available to the web platform.
The purpose of this page is to highlight some of the team's best work as an example of the kinds of challenges that there are to work on.
An important principal we as a project team follow is to ensure the content is as accessible to anyone who wants access to it. That means paying special attention to accessibility, translating the content to as many languages as possible, and using progressive enhancement to give the best experience to those users on modern browsers, while ensuring the site is still usable on those on older browsers. Additionally we are obsessive about performance and adhering to other best practices in web development. This takes real effort from the development team, but we feel it is well worth it!
More details of this is in our Accessibility Statement but we spend a lot of time ensuring the site is built to the best accessibility standards we can with the appropriate use (but not overuse!) of ARIA atributes where necessary. We use various tools to achieve this including AXE, WAVE, Lighthouse and the Firefox Accessibility tester and attempt to address all issues which are not false positives.
We're not claiming we're perfect, but we make a genuine effort to address all Accessibility issues that we are aware of.
The site was built form the beginning as a multi-lingual site and we have separate Translation Teams continually working on back porting old content to various languages. That brings a number of technical changes on how to implement it, how to avoid duplicating code as much as possible to make maintenance easier and to ensure we handle SEO appropriately.
It also brings UX and testing challenges as the different languages will have different content available at different times and, in many cases, will not have pages available in each language.
In line with our ethos, we do not assume that all our readers will be running the latest browsers and have access to all the most recently released features that we use on this site. This means that, although we encourage use of new features in JavaScript and CSS, we ensure the site is useable and content is readable even on browsers and devices that do not support these.
At the end of the day, the content is what is most important about the website and that should be easily rendered by even the most basic browser. Any nice features, for either our users, or to make development easier for ourselves on top of that, is secondary to that. So we encourage making use of the latest features, but not to be dependent on them.
At present the site works well on any of the currently commonly used browsers, right back to Internet Explorer 11 - though those browsers may miss out on some of the nicer features like our Fonts, our fancy index sidebars, or our contributor filters. Some of these would be possible to add even in older browsers, but we feel are not essential and this increases complexity and risk of errors. The important point is the main site and content is available.
This also means the Web Almanac is also available to any device capable of rendering HTML, is fully readable in reader modes of browsers and also can be used in smaller devices if you really desire 😀:
Many of us involved in the Web Almanac are web performance advocates and so of course we ensure the website is a performant as possible despite the wealth of rich data available.
We are pleased to have developed a highly performant and responsive website – despite the time pressures associated with the project and the fact it is developed by volunteers:
The web development team carefully considers all new enhancements and ensure they are implemented as efficiently as possible, including ensuring images are of the appropriate sized and format depending on the devices capabilities, serving assets like fonts locally, measuring our site performance using Web Vitals
As well as all of the above, we ensure we use good semantic HTML, that our websites pass HTML and CSS validators, and that changes are peer reviewed. We also ensure we are developing using good SEO practices to ensure our content is easy to find. Having access to a wealth of web experts allows us to reach out to them on various issues where the answer is not obvious!
And despite being a static site, we still follow best security practices, including using Content-Security-Policy and privacy protecting features like Feature-Policy:
The Web Almanac is available as both as an online website but is also available to download as an Ebook: 2019 English Ebook and 2020 English Ebook. Or course it is also available in any other completed translations too: 2019 Japanese Ebook.
The Ebook is generated via the website using the CSS Paged Media Module. This is not yet well supported in standard browsers, but specialist tools exist which allow you to generate a PDF from the HTML, CSS and JavaScript we all know and love.
As discussed in our Accessibility Statement we also ensure this is an accessible Tagged PDF which meets the PDF/UA-1 standard. Again this accessible PDF is generated directly from our website.
The Ebook is also available in print-ready format, meaning you can send it to your local printers to get a physical book!:
These are just some of the newer APIs, or more advanced techniques that we use on this website (in no particular order):
IntersectionObserverprefers-reduced-motion- Effective Connection Type to decide whether to download expensive resources
- Native lazy loading images and iframes
- Web Vitals to measure performance.
- Canvas
- CSS Paged Media Module
-
Subsetting and using
unicode-rangesfor best font performance. -
<picture>element to serve larger image sizes on higher resolution screen, and WebP format to those that support it. - Embedded SVGs icon system
We make a lot of use of GitHub Actions to help with developing, testing, build and releasing the website, including:
We created a GitHub Action to automatically track chapter progress which helps project manage such a large project with so many contributors based all across the world.
Our actions automatically lint all our code to keep it bug free and enforce a consistency of style. We also perform test code changes, which again helps with the spread of the team and new team members joining all the time.
Using such a variety of technologies and having such high standards occasionally means we spot issues with some of the tools, and dependencies we use. Many of these are open source and we have committed improvements to the Github Super linter, the Calibre Image compressor, and the Flask Talisman security library to name but a few. These changes make our site and development practices better, and hopefully allow others to benefit as well.
Developing on the Web Almanac gives you a wealth of opportunities to work on a variety of interesting web development techniques!