One of the great things about our industry is how passionate people are about helping each other learn. Be it articles about the latest and greatest techniques that they’ve discovered, or blog posts about new web platform features that have landed in modern browsers. All this content–often created by people in their spare time–has one downside: it is often unmaintained, and with the frequency that certain features or APIs can change syntax or new prefixed implementations arrive, the content can become outdated. If the content appears high up in search results, or is linked from influential sources, it can lead to developers copying code that may not work in as many browsers as it could. It can also harm the adoption of the latest version of the spec.
With that in mind, I created the Stale repository on GitHub. I intend to make this a place to crowd source the discovery and eventual fixing of out of date content about web platform features on the web. If you come across an article or post that is out of date, then open up an issue linking to the post and what information is out of date. If the author has a GitHub account, @mentioning them in the report will automatically ping them, to alert them to the issue. This has been effective so far.
So what issues qualify? There is no hard and fast rule, but the easier a post is to stumble across when searching for how to use a feature the better. I’d like the first few pages of search results about a given feature to lead to up to date and correct content. Articles, reference materials, and polyfills are usually more important to keep up to date than blog posts that are often tagged with a date and are more often understood to go stale over time.
As for what features to report, I image this as a place to report content about web platform features built into the browser rather than features of libraries such as jQuery and so on, but I’m open to feedback there. Examples of reports so far include outdated content about CSS Flexbox, Gradients, Fullscreen API, and Screeen Orientation API.
I see four main areas where content goes out of date. The two most critical are if the syntax changes (e.g. Gradients and Flexbox), or if new implementations come with a prefix that isn’t covered in the article. Perhaps a lower priority is if the compatibility information is out of date. I personally wouldn’t bother reporting this if it is a blog post and there is no other outdated information such as missing prefix. I’ve also included a tag for bugs such as a bug in the code samples, or a bug in an implementation that either needs worked around (and is important enough to mention) or is no longer needed. I’ve not really used this latter tag as of yet though.
How to report an issue
Reporting an issue is simple. Just open a ticket in the issue tracker and include the following information:
- URL
- The address of the content in question
- Issues
- A list of the issues in the post, along with any fixes needed
- Contact
- Contact information of the author or site. @mention their GitHub user name if they have one.
- Tags
- I’ve included tags for the technology, the feature, and the type of issue, so that similar issues can be grouped.
I decided to have individual tickets per article rather than one per feature, so that they can be closed something is fixed. There are often common issues that need to be described, so I’m thinking of using the Wiki to catalogue these, along with the required fixes, so that they don‘t needed to be typed out each time.
Why report issues?
Because keeping information up to date is often as important as writing it in the first place, and the original authors are often not aware that their content is no longer up to date. Much of it was written in people‘s spare time, and it is a full time job in of itself to keep up with all the changes that are going on with the Web Platform.
You might wonder why you should report it here rather than in the project’s own GitHub repo. By all means do both and link to one from the other. Not every project or site is on GitHub, so while many sites have a place to directly report issues, not all do. It is nice to have an overview in one place of all the issues with a particular feature.
How to fix an issue?
Usually an issue can be fixed in one of two ways. Either the content gets updated to reflect the current situation, or a deprecation notice is added, linking to a place to find out more current information. Flexbox has its own boilerplate notice made by Paul Irish. I was also thinking of making standard notices for all common features on the Wiki.
If the content lives in a GitHub repo (or similar) or a Wiki, it is often easier to fix the issue yourself, rather than waiting for the author to find time. Consider making a pull request or directly editing the wiki in question.
Once an issue is fixed and went live, note it in the report and close the issue.
Successes so far
Although this initiative is yet young, we’ve already had a number of fixes. Out of 44 issues, we’ve had 9 fixes including:
- Moz Hacks
- MDN x 4
- HTML5Rocks x 2
- TutsPlus
- the-haystack.com
Additionally three other sites were fixed before I started cataloguing them on GitHub. Of the 34 currently open issues, at least one has been fixed but is yet to go live (HTML5Please), and three are in progress (HTML5Demos, Sitepoint, and CSSTricks.). While it is clearly early days, it looks like the approach is working.
Any help you can all give, the better and more accurate the web (docs) will become.