Choose documentation platform

[jwflory]

Summary

Establish a documentation platform for hosted documentation about MagicBox projects

Background

Effective documentation is critical in technical projects – open source or otherwise. However, it's especially helpful for MagicBox because of the small team size and need to engage with the open source community.

Better documentation for MagicBox means…

1. New contributors / contractors learn the pipeline / software quicker
2. Design decisions are better documented (less time back-tracking)
3. Enables other contributor-oriented documentation (e.g. issue / PR templates, see Create issue / pull request templates for core MagicBox projects #3)
4. Easier to tell a story (e.g. Opensource.com, see Write an article about MagicBox for Opensource.com #8)

So far, a lot of highly technical information is shared through Medium blog posts, which is helpful, but blogging isn't effective as a long-term strategy for referencing technical information for MagicBox. This type of information should live in documentation, while stories behind how it happens is better suited for blog posts.

Details

Choosing a platform should be based on what is most intuitive and easiest to maintain for the team. A popular platform is ReadTheDocs, which uses a Python-based toolchain. Thus, it also makes it an especially fantastic tool for Python projects, but it is still great for any programming language regardless.

I want to do additional research to see if there is a Node / JavaScript-tailored docs platform, since many of our projects are in Node. However, I think ReadTheDocs may still be the best solution for this.

Outcome

Better documentation means a better experience for people to contribute to our projects; enables us to bring new people into the community easier and also provide reference points for various design decisions in the future (i.e. why we did something the way we did)

[jwflory]

2018-01-16

What was done

Independent research for JavaScript-style documentation toolchains proved that ReadTheDocs is the best tool for the job (see readthedocs/sphinx-autoapi#7). In #13, I set up a basic Sphinx¹ environment in the MagicBox repo. I was able to convert one of our wiki pages (Administrative boundaries) into a hosted doc page. Check it out here!

What's next

We have a lot of repo sprawl. I want to look into using a "master" docs project, based from this repo, and then others, like aggregate_airport_mobility, coordinates_to_admin_id_server, and magicbox-open-api could be sub-projects underneath this one. I need to look into the technical how-to of doing this.

I also want to look into how we could bring programming documentation into the docs in an elegant way. For Python projects (like aggregate_raster_by_shapefile), this is powerful. I'm not sure how to do something like docstrings in JavaScript / Node, but I intend to find out if it's possible with ReadTheDocs / Sphinx.

---

¹ Sphinx is the underlying tool that powers sites like ReadTheDocs. Sphinx is the tool, ReadTheDocs is the platform.

[jwflory]

I'm going to say the "choosing" part of this is done. Now, it's about getting a start to demonstrate something meaningful with this tool. I'm focusing my efforts in documentation on the coordinates_to_admin_id_server project for now.