As we announced a few months ago, as part of our sponsorship of the Express project, we’ve been working hard on improving the Express.js documentation. Developer and author Hage Yaapa has done much of the heavy lifting on this project, with guidance from me, StrongLoop’s technical writer, and with invaluable advice and input from Express lead maintainer Doug Wilson.
Here’s an update on where we are with Express documentation and what’s coming next.
When we started there were over 25 open issues and several open PRs in the GitHub repository. Many of them were related to all the 4.x changes to Express; others were just missing information, or mistakes and typos. We’ve now merged/closed all the PRs, and fixed almost all of those issues, with help from Doug Wilson and other helpful members of the Express community.
Here’s a list if you’re curious about the details:
- #155 – Doc error (req.route.params)
- #157 – Typo error: req.pipe() instead of res.pipe()
- #158 – Document app.route / app.mountpath
- #159 – Explain that .param doesn’t get inherited in mounted routers
- #162 – `req.accepted` still in documentation
- #169 – Update router docs to include new mergeParams option
- #173 – 404 link in FAQ
- #167 – Describe options that can be passed to the depends used by express
- #178 – document req.baseUrl
- #179 – document “query parser” settings
- #180 – document “trust proxy” settings
- #182 – update app.use documention for multi args
- #183 – add all the non-string things that app.use takes as a path now
- #184 document headers option for res.sendfile
- #185 document req.hostname
- #186 – document that req.param cb is only called once
- #187 – document how to use DEBUG to check routing issues
- #188 – document all the new options express.static accepts
- #189 – document “etag” settings
- #190 – document all the new options res.sendfile accepts (like dotfiles)
- #191 – address how render works
- #193 – document res.sendFile
From Jade to Markdown
From the standpoint of enabling more community contributions, the most significant improvement has been changing the authoring format from Jade to Markdown. Jade is a perfectly reasonable templating engine, but is not ideal for authoring documentation, being essentially a finicky version of HTML. Markdown is dead simple and is the lingua franca of GitHub (and other sites).
We converted all the existing content from Jade to Markdown. The site still uses Jade to divide content into modular components, glue everything together, and ultimately generate the static web pages. There are a few special cases where Markdown doesn’t work well; in these cases, we fall back to HTML within Markdown files. For example, while Markdown table syntax works well for simple tabular data, it becomes unpredictable with complex content within table cells. We’ve got a short GitHub wiki page that describes how Jade, Markdown, and HTML work together in the site, with a few guidelines and tips for authors.
Authoring in Markdown is undoubtedly easier than Jade, and our hope is that this will encourage docs PRs from the community moving forward. A large part of the power of an open-source project like Express is the participation of its community. So, we’re hoping that this change will encourage the community to become more engaged in writing and maintaining documentation. This, in turn, will improve the usability and approachability of Express overall.
In the next few weeks, we’ll be wrapping up the next phase of this project.
First, we’re adding a new menu navigation system, to provide more organization and hierarchy to the documentation. Currently, the site has a single-level navigation menu system that’s simply too restrictive for the amount and complexity of the information. We’re going to add simple drop-down menus for another level of hierarchy. This enhancement will make the site easier to navigate and is in the works now; it should be published to the expressjs.com website very soon.
As part of this, we’ll be rolling out a new content architecture (topic organization) that will split out “Getting Started” and “Advanced Topics,” as well as creating a larger and more modular “Guide” section. We’ll be moving some of the useful information now buried in the API section into the appropriate topics, and narrowing the focus of the API documentation to be specifically on use of the API. Initially, for some new topics there will be some “placeholder pages,” but eventually–and hopefully with input from the community–we will fill these in.
There will be quite a bit of “clean up” as we move ahead, both in non-technical content on the site (some of which is still rather outdated), and in technical documentation. When the dust settles, Express will have a complete, usable, easy-to-understand documentation site on par with other frameworks. Importantly, it will have an infrastructure that encourages community participation to help maintain the accuracy and quality of the documentation as Express moves into the future.