Proposal for implementing the new WAI Site

Introduction

This text outlines the general approach for implementing the new WAI Site. It first explores the challenges of different implementations and then describes the best approach according to my thoughts.

Objectives

We have certain goals that need to be reached to call the transition a success.

Ease of use.
Updating content should be easy and straight forward. Making changes to pages should be possible without much knowledge of HTML, CSS, and JavaScript if the editor chooses to do so, for example using Markdown.
Sustainable features.
The pages need to be generated automatically. The HTML output needs to be consistent, which allows us to make changes globally, for instance, when we introduce new features or bug fixes. Also, this helps us to do more with the information we have – for example we can collect all pages with a certain tag and create an overview page or generate an RSS feed.
Automatic creation of navigation.
The navigation needs to be created automatically, according to the nesting of the document in the source and additional parameters to make it easier to update the site.
Ensure simple redirects.
Old content which is still relevant needs to point to new content with a blurb of text and a link. Replaced content needs to be forwarded to the new pages consistently.
Easily enable future features.
With a good foundation, the new WAI site can be a role model for implementing new technologies in an accessible way. A good example would be adding progressive web application functionality.

First Challenge: Technical debt and URLs

The website w3.org/WAI developed over many years. A result of this approach is a technical debt that shows in hundreds of pages with

outdated content,
orphaned content,
irrelevant URLs,
impossibility to determine where current content is,
hard to update structures and content.

Possibilities

We have several possibilities:

Keep w3.org/WAI and just rename and replace files. Using our old structures with navigation.

This approach would only further increase the problems with the website. As we do not want (and should not) remove all content from w3.org/WAI, this first approach seems hard to do and adds an unnecessary layer of complexity to the redesign.
Use another sub-directory, for example, w3.org/accessibility. We would still be checking in content through CVS, which only w3.org staffers can do. [I think only staff should be able to post updates to the site in any case. ~Shawn]
Use a w3.org sub-domain, for example, wai.w3.org or accessibility.w3.org.

The move to a sub-domain could help us separate w3.org and our technology stacks, making it easier for us to update and host our data. Theoretically, we could even host directly from GitHub pages, but we might have too much traffic to do that in a performant way.
Move to a separate domain, for example, w3c-accessibility.org.

While enticing, the perception could be that WAI is something different from w3.org. Also, there seems no really good domain name (like accessibility.org) available. Apart from those considerations, technically it is the same as option 3.

Recommendation

As we need to get out of the technical debt spiral, I strongly suggest using a sub-domain or at least a new sub-directory.

After discussing the issue with the WAI Team, a sub domain wai.w3.org is the preferred solution.

Pro sub domain:
- Clear separation of old and new content.
- Clear one-way redirects
- Keeping the familiar WAI brand.
Contra sub domain:
- Not done (yet) for activities.

Pro sub directory:
- Clear separation of old and new content.
- Clear one-way redirects
Contra sub directory:
- Likely losing wai in the URL
- No really good options for URLs: w3.org/WAI is taken by the outdated stuff, w3.org/accessibility is too long and nobody wants to type it, w3.org/a11y is not accessible because nobody knows of the number thing, can be confused with ally on printed materials, for example.

Second Challenge: CMS

Currently, the WAI site is a collection of pages that are held together by a navigation script and manual work. Some resources are stand-alone that probably don’t need to be (for example the tutorials).

Possibilities

Use of a classical PHP-based CMS. The advancements are that this allows for more interactive features, like commenting. Keeping it up to date is much harder, we’d need a database which would affect our current editing process on GitHub.
Use of Jekyll to generate a static website. We use this approach with the tutorials, the Quickref, the Tips for Getting Started and the policies prototype. Jekyll creates a static set of HTML pages that we can upload and update. A preview can easily render on GitHub pages. We can take comments and pull requests from the public.

Recommendation

We are using approach 2 for our current resources, and I see no real need to change the approach. Jekyll allows us to use either Markdown (recommended for new content) or HTML in documents. We can also use both in one document if we need to, for example for demos. This approach should allow us to copy old content to the new site rapidly, too.

Third Challenge: Outdated/Archived content

Currently, we have a lot of 301 redirects configured and we get a whole lot more with the redesign. Our URLs make no sense. Adding new redirects in the same directory, while we are redesigning the site, would complicate things even more. If not done carefully, it might lead to redirect loops and result in a worse user experience.

By using a subdomain or a subdirectory, redirects would not influence each other and therefore be less error prone. Also, it would be clear for users that w3.org/WAI/ is older content, while accessibility.w3.org is current content. We would have all old content archived by default. If there is a document superseding that resource, we can use a 301 redirect. If we don’t feel that everything has been mentioned or that the page is needed for archival/historic purposes, we can just add a notice on top.

Fourth Challenge: RSS feeds/News

The RSS feed was updated semi-automatically by hand. With a CMS, this is not necessary anymore: Whenever a new page is added or changed, the RSS feed is updated. We can (and should) have a special feed for announcements.

An announcement archive is automatically created, and each announcement has its permalink URL.

On using GitHub pages

We use GitHub pages to preview most of our resources already and while there’s a good case of using it for the new WAI site, similar to what the publishing initiative is doing, there are some downsides:

We have millions of visitors each year, will GitHub tolerate us? (From https://help.github.com/articles/what-is-github-pages/ it does seem like they likely do, but what if that changes?)
We use PHP to handle some of the forms on our pages.
- Possible Solution: Put all PHP handlers in a directory of the main W3C website (for illustration purposes: w3.org/WAI/php/) and, after successful submission, redirect to a page in the main WAI site.
We want to have a preview version on GitHub pages for us, so we can make changes and see how they work without making the changes to the live site.
- Possible Solution: Have a protected (maybe even private) repository that displays the production website. When we want to make changes we can then merge the changes into this protected/private repository.
It is likely that we have some external Jekyll projects that we want to reference and use in the page, for example, the Quick Reference. It is built externally and we probably don’t want to port all of it into the new site.
- Possible, but clumsy, Solution: We might be able to push pre-build versions to the repository and then reference that from the main WAI repo as a submodule.
The .htaccess proxy to GitHub adds some delay, which means the site won’t be so fast.

If we used GitHub pages to host the WAI website, and decide to use a subdomain, all Systeam needed to do is to change the CNAME entry on the domain:

Timeline

July – August 31: Build HTML and CSS components.
August 31 – September 13: Import content, build prototype.
September 13: Import edited content, refine prototype.