As famously observed in the seminal book The Cathedral and the Bazaar, developing software in the open source “bazaar” provides many advantages. The benefits of open development are now widely recognized and have been key to the success of Node and web technology in general. At StrongLoop, we’re strong believers in open development, and we’re developing almost all our software, including the LoopBack Node application framework, as open-source projects.
Unfortunately, it’s also widely known that the quality of open-source project documentation is often lacking. As a technical writer with over 20 years experience in developer docs, I’ve observed that documentation is the “red-headed stepchild” of the software world. Too often, it’s an afterthought, and rarely takes priority. Developers need it and feel the pain when it’s poor, but actually writing good documentation is easier said than done.
StrongLoop recognizes the importance of good documentation, which is why we’re devoting substantial resources and effort to improve LoopBack’s documentation. Making good docs is often labor-intensive, particularly for a complex and powerful application framework like LoopBack. The reality is that, as a small start-up, StrongLoop has limited resources, and only one full-time technical writer (me) for many disparate projects, including LoopBack, Express, StrongLoop’s Node Ops solutions (StrongLoop Controller and StrongLoop Agent), and other products.
To help ensure that LoopBack has the best documentation possible, we’re going to leverage the power of open development. We’re opening up the LoopBack documentation on docs.strongloop.com to community edits. We’d love to hear your ideas about what to do in GitHub, or on the LoopBack Google Group. Even more, we’d like to see the community become actively involved in improving the docs. We invite you to login to our wiki at docs.strongloop.com with username “community” and password “strongloop”. Please read Contributing to LoopBack documentation before editing.
LoopBack’s API docs are created from comments in the code. So, contributing to the API docs is just like making a code contribution–use a PR in GitHub.
To kick start contributions, we’re offering LoopBack swag to the best contributors:
- Make a small fix (correction or addition) and we’ll send you a LoopBack sticker.
- Make a significant improvement (new or improved example code, new section, fixing one of the known doc issues), and we’ll send you a T-Shirt.
- Make an extra-awesome contribution and we’ll send you a StrongLoop hoodie.
Who gets what is at our sole discretion, but we really want to encourage participation, so rest assured we will reward good-faith efforts.
IMPORTANT: Be sure to provide your email or GitHub ID in the comment field when you make the contribution. Since we’re using a shared login, this is only way to ensure you get credit for your work! See Contributing to LoopBack documentation for details.
What we’ve done lately
If you’ve been keeping up with the LoopBack Google Group, you know that we’ve focussed special effort on documentation lately. The whole team took a sprint to work primarily on docs. We did quite a bit of reorganization and cleanup, and among other things wrote and expanded several articles on how to implement custom logic before responding to client requests, including:
- Adding logic to models – adding remote methods, remote hooks and model hooks.
- Defining boot scripts – writing scripts that run when the application starts.
- Defining middleware – adding custom middleware to the main application script.
We’ve also added a lot of examples with accompanying tutorials. We’re working on a more advanced comprehensive example.
What is complete documentation?
For developer docs, there’s often even disagreement about what “complete documentation” means. I’ve actually had developers tell me “the code IS the documentation!” Of course, that’s a rather extreme (and, one hopes, facetious) view but, especially in the case of small open-source projects, might not be too far from the mark.
At the most basic level, “documentation” means just API documentation: what are the functions, their signatures, options, defaults, return values, and so on. For any substantial project, API docs are necessary, but not sufficient. API docs are no more “documentation” than flour, eggs, milk, and sugar are cake.
Beyond API docs, you also need to create “recipes” for using the API, with reference to the API docs. These “how to” articles are procedural and task-oriented. This is the cookbook that shows you how to turn the API “ingredients” into delicious chocolate cake–in our case, an awesome LoopBack application. Related documentation includes conceptual docs that explain concepts or principles behind the recipes.
Finally, the “icing on the cake,” as it were, are tutorials that walk you through the steps to create applications with basic features. Tutorials are important tools for teaching but take the most time to write. Typically, the tutorial is the last thing you can write, depending on how well-defined the “developer experience” is.
We welcome contributions in all these areas, and we’ll keep you posted on progress. Together, we can bring the quality of LoopBack’s documentation up to par with that of the framework itself.
- 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.