Documenting the Modules

My work on creating the documentation is continuing well. I needed to spend some time at first learning how to use react-router, a library that allows you to get URL routes in your Single Page Application (SPA). We need the documentation to behave as users expect it to. They shouldn’t know we’re making it a React SPA.

I’ve documented how the new central config object (used by all modules) works, as well as how to install and run the individual modules. I’ve also documented how the user accounts work in the Analytics module (my team mate created a much more robust system where usernames and bcrypt-encrypted passwords are stored in the MongoDB database). My next steps will be to document the AWS bundle (I wanted to wait until the individual modules were more polished and tested before tackling this) and then to polish the whole documentation. I want to make it read well, to be as simple as possible. There’s a certain writing style that good documentation uses to accomplish this.

An example of great documentation I’ve read before to inspire me is the MongoDB documentation, including how they describe the database itself, the language-specific drivers, and the language-specific ORMs. From top level concepts to low level code examples, it’s very clear. And it has helped me learn the tools we use on our project, which center around MongoDB.

I also want to make sure the documentation renders well on mobile phones. This is a bit of a stretch goal… Most developers read documentation when they’ve sat down to deep dive into something new and try to code something up, but you never know… We want this to be as welcoming as possible to potential users and open source contributors, including people so busy they only have time to look at the documentation while they’re on their phone on the TTC.


Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s