We’ve heard clearly from the Express community that one of the areas that most needs attention is documentation. We have plans to contribute in this area for the short, medium, and long term.
Meet the documentation team
Allow me to introduce myself: I’m Rand McKinney, the technical writer at StrongLoop. For almost a year, I’ve been working on LoopBack open source project documentation, and more broadly I’ve been writing developer docs for over 20 years. In the last few weeks StrongLoop has been collaborating with members of the community and specifically with author and developer Hage Yaapa to improve the Express documentation.
What improvements can you expect?
In the short term (next 2-6 weeks), we’re going to work on resolving some of the open issues and pull requests. We’ve already started picking off some of the easy fixes  . These are trivial fixes, and a number of the open issues and PRs may fall into this category, but cumulatively these kinds of things add up to improve the quality of the docs.
Some of the other open issues have brief descriptions, but lack details. We’ll be working to fix these in the coming weeks, and we invite you add any comments or specific information to fix them. I’ll be working with Hage and you, the Express community, to make these improvements and updates.
How can you help? If you notice something wrong, incomplete, or just unclear, open a new issue. Please check the existing open issues first to ensure someone else has not logged it already. Even better, if you’re sure of yourself and want to contribute a fix, submit a PR to address one of the open issues. It would be helpful if you commented on the issue first to let us know that you’re going to work on it, to avoid any duplication of effort.
We’re going to review and update all of the content needs for version 4. Some of the open issues address this, but we need a methodical review of changes and additions in 4.x. Ideally, we can even mention what version of 4 is required (for example, “added in 4.5”).
I’ll also do a comprehensive edit pass, to make sure the docs are clear, easy to understand, and is consistent in usage, formatting, and all the other stuff that makes docs more effective but is often neglected.
In the medium term (next few months), we want to more broadly improve the organization and information architecture of docs. Right now, the technical docs basically consist of three parts:
The “API” section has a lot of good information but much of it is not really API reference information, but is better suited to a well-organized “Guide”. Likewise, some of the “FAQ” topics should be in the “Guide”. We’ll be working to create a more comprehensive developer guide that explains in a clear and well-organized way what you can do with Express and how to do it. This may require enhancing the site navigation, which is fairly limited at present. We’d also like to add new sections on using “components” (some of which used to be called “middleware”) and other “advanced topics” such as on creating compatible template engines.
In the long run, we’d really like to make it easier for the community to become involved and contribute to the documentation. Currently, the docs are sourced in Jade, which is not ideal as an authoring format. I’d like to modify the app behind expressjs.com to enable authoring in markdown, which is a much easier format to use and maintain than Jade. Some time soon, I’ll create a gist and/or issue to summarize this goal, and begin a community discussion around the best way to accomplish our goal of making it easier to create and update docs.
- What’s in the upcoming Node v0.12 release? Six new features, plus new and breaking APIs.
- Ready to develop APIs in Node.js and get them connected to your data? Check out the Node.js LoopBack framework. We’ve made it easy to get started either locally or on your favorite cloud, with a simple npm install.
- Need training and certification for Node? Learn more about both the private and open options StrongLoop offers.