Since we last checked in, we’ve made a lot of progress both with the Express documentation itself and in the “infrastructure” of the expressjs.com site. Although developer and author Hage Yaapa and I have been leading the documentation efforts, we’ve been working closely with Express lead maintainer Doug Wilson, and with the community as a whole.
In the last four months, we’ve merged over 50 pull requests (PRs) and closed over 30 issues. While many of these were small corrections or trivial updates, some were significant improvements, as I’ll outline below. In general, one of our primary goals is to empower the community to help improve and maintain the documentation.
Move to Jekyll from Jade
As you may recall, last Fall we moved the content of the site to markdown from Jade; but the site still used Jade to “stitch together” the pages and provide structure. This made the content easier to edit, but still required you to build static HTML pages using a makefile and then check in both the markdown and the resulting HTML. Quite often, we would get PRs with only the markdown or the HTML file(s), requiring us to either add the missing file(s) or ask the contributor to do so. Not a big deal, but tedious and an unnecessary barrier to community contributions.
Because we want to make the site as easy as possible to maintain and contribute to, after some discussion, we decided to make the site a GitHub Pages website served through Jekyll. Jekyll is a static site generator that uses a variant of Markdown known as Kramdown and a simple but powerful template system called Liquid. Jekyll comes built-in with GitHub Pages.
But wait — you might be saying to yourself, “shouldn’t we be using Express for the site?” “Shouldn’t we be eating our own dogfood?” Although we love Express, we don’t want to be in the business of creating and maintaining a documentation content management system. Our focus is on providing great documentation for Express. Since we are already using GitHub Pages to host the website, it makes sense to leverage the capabilities it provides. It’s all about using the right tool, for the right job, under the right circumstances.
In addition to moving to Jekyll, we made tons of general improvement — far too many to list in detail. Here are some of the highlights…
We revised 4.x API docs to have more logical organization, specifically:
- Separated properties and methods.
- Alphabetized property and method entries.
- Explicitly listed all supported HTTP methods.
- Improved documentation for application settings.
- Standardized formatting of method options parameters in tables, with an “Availability” column to note when a particular option property was added, if appropriate.
We also added:
- List of known/fixed security issues.
- New database integration page.
- A simple mechanism to highlight announcements on the home page (for example, new releases).
I also did a comprehensive edit of the site, to ensure consistent wording, usage, grammar, and spelling. I also eliminated some redundant content left over from the previous reorganization. This just makes the information easier to read and understand.
Express has users around the world, and not all of them understand English. We want to make the Express documentation accessible to everyone, regardless of what language they speak. To this end, we recently created a structure and instructions to translate the documentation.
To be clear, we’re not actually translating the documentation ourselves, but simply providing a simple way for people in the community to put their translations on the site. We look forward to seeing contributions in this area. In the future, we’ll be promoting this and asking for help with translation.
Moving forward, we will of course continue to maintain the site and accept PRs and issues. As time permits, we’ll improve documentation of existing features. Express version 5.0 is in the development stages, and will be released (in beta) some time in the next few months. We’re keeping an eye on its progress, and will help provide complete documentation when it’s released.
Although we’ve been leading the charge to improve the docs, Express belongs to you, the community, and the most important thing is to empower you to contribute to the effort. In general, we’re happy with the progress we’ve made, and we’ll continue to listen to you to ensure the documentation meets your needs.
StrongLoop Arc is a graphical UI for the StrongLoop API Platform, which includes LoopBack, that complements the slc command line tools for developing APIs quickly and getting them connected to data. Arc also includes tools for building, profiling and monitoring Node apps. It takes just a few simple steps to get started!