I was on my way into the office one morning when I saw a link to the results of the 2017 Open Source Survey, released by GitHub. I’m almost certain I filled it out myself at some point, but seeing the summarized results was just as important for me, as our project is completely open-source and as such, any recommendations would be highly relevant to us.
… [the survey results] highlight some of the most actionable and important insights about the community.
Imagine my surprise when the number one insight was that documentation is frequently overlooked, yet was highly valued by consumers of the software!
I’m not going to respond by saying our documentation was fantastic… in fact, our documentation has quite a ways to go in order to be complete. Our documentation journey has had quite a bumpy ride, with its humble beginnings found in the repository’s README.md, expanding to the nearby repository wiki, and then a move to ReadTheDocs with our entire documentation converted to RestructuredText.
We even made some attempts to internationalize our documentation, so that users in other countries could install and configure their NodeBBs.
Unfortunately, we fell behind a bit because of the following:
- Developers really don’t like writing documentation, or don’t even realize that documentation is out of date
- RestructuredText is not as intuitive as Markdown
- Any changes to the english language docs could not be easily propagated to other localized docs
- Updating the documentation involved a build step that didn’t always succeed
- Each author of an article would often write in their own specific style, leading to pages that didn’t seem cohesive, thematically.
- Building documentation locally wasn’t easy and led to situations where blind commits were made, followed by builds, followed by documentation that was clearly broken, followed by hasty commits to fix various syntax errors. (As much fun as it is to develop on prod…)
We’ve even run into multiple situations where forum users or clients of ours investigate problems and find solutions in our very own community support forum, instead of the official documentation!
A forum is a fantastic resource for problem solving, especially since many of our users’ first attempts at seeking help would be googling. However, we’ve all been party to discussions where a question is asked, followed by a brusque "search the forum before asking" from some forum regular, and that symptom is why I feel strongly that the official documentation should work in-tandem with the support forum.
So what’s new?
Over the past week, we’ve cleaned up the documentation and migrated to a new host (our own). The software is based off of MkDocs, although the URL has not changed (https://docs.nodebb.org).
We’ve rewritten a whole bunch of articles and made some much-needed updates to others, and shuffled the hierarchy around so things should be easier to find.
We also added a webhook listener to the repository so any committed or merged changes will show up on the live site immediately, and mkdocs makes it quite easy to develop locally (mkdocs serve with livereload integration ftw!)
As always, we’re open to feedback on the docs1. What sections need fleshing out? Let us know in the comments.
1 Yes, I know the plugin hooks pages are less than ideal. We made the decision here to keep updated using an automated tool, but we can’t add more context to each hook because as hooks get added and/or deprecated, documentation might go out of date…