Why we use SelfAPI


#1

Carolyn Stransky recently asked on Twitter about open source projects that auto-generate their documentation:

And since we wrote our own automated documentation (and tests) generator—SelfAPI—I reached out to her.

Below is the quick Twitter DM interview that followed:

Project name or link?

Janitor, an online development service for Open Source projects (source code)

What do you use for your docs?

What did you use before that?

We didn’t have documentation (or tests) initially, because the priority was to demonstrate that online/web-based development actually works, and is convenient & fast.

Why did you switch?

Once the system worked, it became obvious that we needed documentation (and tests) to make the project more welcoming and stable. However, it was still mostly just me, and I didn’t have time to write very long docs, or many tests, let alone maintain them forever (docs tend to become obsolete extremely fast, and the prospect of constantly rewriting them alongside the project’s code was daunting). So I wanted something as automated as possible, some process where docs and tests are forced to remain in sync with the code.

Also, I wanted to write a JSON API, and these usually cover most of your project’s features (so writing docs and tests for your API will cover most of your project). I looked at Python’s Flask and Flask-RestPlus, which looked awesome, but Node.js didn’t have nice things like that.

So I decided to write my own API system, that forces you to define title; description; and 1 or 2 examples along with each API handler, and it turns out that this is enough to automatically generate documentation (the API reference) and to automatically test your handlers against their own examples (ensuring that your docs’ examples actually work and always remain relevant).

SelfAPI is very lightweight and took me 2 or 3 days to write, and using it suddenly made Janitor go from 0 docs or tests to almost full docs & tests coverage (and also gave it a rock-solid JSON API). And the best thing is that there is no maintenance cost to keep them up-to-date: for any change to the code, you also have to update the meta-data used for docs and tests, and it’s pretty automatic since everything lives in the same place: SelfAPI code example - list Janitor projects.

We also installed a Discourse community forum, in order to “automate” another documentation process: Anyone can ask any question about the project there, and our replies instantly become de-facto documentation (without us having to edit a wiki, website or guide somewhere else): Discouse example - Is there a business plan?

FYI this whole docs & tests initiative started when the project started to work: We had to come up with docs & tests basically from scratch, so I asked JeremiePat for advice (he has a lot of experience with this), and everything we did flowed from his really great insights in GitHub issue #41.

I’m also really interested in why you would start your own? And how long did that take you to build?

I wrote my own because Node.js didn’t have nice automated things like Python’s Flask and Flask-RestPlus (on NPM I found tools just for docs or just for tests, but everything seemed very work-intensive to integrate and also to maintain, with almost no automation). SelfAPI took me 2 or 3 days to write (a single JS file) and then I got to use it to write a self-documented & self-tested API for Janitor. Now I have up-to-date docs & tests basically for free, and forever. :smiley:

Thank you Carolyn for the great questions!