Project Documentation Systems and What They Mean

Documentation. It’s a scary word to some people, in the context of software or code documentation. There’s a handful of documentation systems out there, with their own advantages and disadvantages. But that’s not what I’m here to talk about. Instead, I’m going to talk about how using each system happens to reflect on the project/the developers, and what to expect in terms of the quality and quantity of the documentation when you find some using a specific system.

This is generally ordered from “worst” to “best”, although these are obviously subjective categories.

Type 1: Only A Discord Link

Fuck you.

I hesitate to call projects that use this undocumented, because that’s not true. The documentation does, in a sense, exist; they’re just spread between various people’s memories and thousands of messages people shit out into a channel.

Really, this is worse than just being undocumented because there’s a faint hope that you might actually be able to find what you’re looking for if you just tolerate joining a brand new random server for long enough. This is never the case.

Between the non-functional search system (that hasn’t been ever functional since it was introduced), a legion of snooty Proficients who are more interested in jerking off about how much they know and how little they are willing to help you, and the complete inability to archive anything making every server a ticking timebomb (ranging from being hit with a rogue mod to the server owner having a minor breakdown and deleting everything), all of the information stored on Discord servers is functionally inaccessible. You may look through the display case and find there is nothing there, but everyone insists that you’re just not looking hard enough.

Type 2: Undocumented

A project can be undocumented in two ways: they just didn’t write any documentation at all, or the source code/program is the documentation. The former type is usually made by either very inexperienced developers who don’t know any better, or very experienced developers who are proud of having all of their creations completely unusable. Trying to figure anything out when presented with either of these options is an exercise in insanity.

Type 3: Automatically Documented

(e.g. docs.rs, Sphinx autodoc, or those stupid OpenAPI webapps)

Functionally undocumented. Trying to use projects like these are like being given a picture of a piece of furniture, a list of parts, and then being kicked in the balls and told to assemble it yourself. Yes, it is possible - of course. But it’s not enjoyable, and you’re going to be spending a lot of time using a disgustingly dysfunctional search engine (or worse, asking on Stack Overflow) in a hope of screwing the parts together.

Bonus points for being combined with the first type, where you will inevitably ask in a channel for help putting things together only to be redirected to the useless documentation, and scoffed at for doing it wrong when you eventtually figure it out.

Type 4: MkDocs, GitBook, and friends

If it’s on a ReadTheDocs domain, usually actually undocumented outside of installation instructions. If it’s not, it’s usually a fun family activity of opening the API reference documentation in another tab and having to cross-reference the prose to figure out how to smash them together. T

These are certainly better than nothing, but I find that my “bad project alarm” internally goes off every time I see a project that uses MkDocs, and I’ve rarely been wrong. It’s no surprise that the current generation of asyncio ecosystem shitware (FastAPI, Pydantic, etc) uses MkDocs.

Type 5: Sphinx

Now we’re getting to the good stuff. Sphinx is infamously hard to use and set up (although a lot of this is, bluntly, user error) so if you can figure out how to get it working that’s usually a good sign. Some projects fall into type #3 and some projects are just sphinx-quickstart, but if its on a custom domain then you’re usually good to go.

Type 6: Custom, own website documentation

(custom in this case means some sort of static site generator)

This varies heavily in quality. Some custom documentation pages are godawful (see: the Kotlin docs, which uses fucking JS so it takes a noticeable amount of time to actually load!), whereas some show a serious dedication to having things documented (see: jOOQ). Sadly, sometimes this documentation is proprietary, heavily outdated (due to contributor difficulty), or plain ugly - things you tend to see less from projects using the standardised documentation systems.

Type 7: Single-page AsciiDoc

I have never seen a bad AsciiDoc documentation page. Its obscurity and slightly higher barrier of entry vs Markdown usually means that projects using AsciiDoc are slightly dedicated to having good documentation compared to everyone else.