Docs are amazing! (Brom Release Notes v0.4.6)
One of the latest update to Brom is focused on how we better onboard new users: Creating beautiful docs.
TL;DR.
Check out the new docs here: [GitHub].
They are still being heavily updated/reformatted (I need to copy a lot of things from the GitHub Wiki into them), so feel free to let me know if something is off! You can:
Write a comment on this post OR
Create an issue on GitHub.
My full message
This will be a shorter release notes message.
I’ve been reading A Philosophy of Software Design by John Ousterhout, after Joshua Levin recommended it to me at work. It spends a couple of great chapters (especially Chapter 15!) discussing the importance of comments and documentation for both developers and new users.
It made me rethink my previous attitude of:
I can give high-level guidance on how to use Brom’s API with examples in the wiki, and that should be enough. Anyone who wants to understand the “nitty-gritty” details can read the code.
Following the ideas from Ousterhout’s book, I decided to adopt a framework for generating documentation. In this case, it was Sphinx.
The benefits of using Sphinx were felt immediately.
One of the first huge impacts was that Sphinx creates searchable and detailed documentation of every class and function in Brom.
You may have noticed that I was slowly updating the Wiki for Brom. I would add documentation for one class at a time and that was taking FOREVER. By running a Python script that uses Sphinx, documentation for the most recent version of the code base was generated automatically (so no need for me to manually update wiki pages later on, if an interface changes). On top of all that, the updates are included in a fancy HTML template that makes the project look a lot cleaner.
Love this.
Another more subtle impact was that it forced me to standardize how I wrote comments. There were (and probably still are) 3 different styles of comments that I use throughout Brom, which makes the code a bit weird to read. I am slowly eliminating this now that I can see the “weirdness”. Luckily, Sphinx clarifies where these different styles are during its processing.
I could wax poetic about all of the nice things that Sphinx offers for new users of Brom, but some of this needs to be “seen” to be believed. Head over to the documentation site for more details: