State of the field: documentation tools

For the first time I am producing documentation for one of my projects in the spirit of Javadoc. In fact, in general I want it to look as much like javadoc as possible, including as boring and thorough…

So far the two most promising approaches look like either Autodoc or Codox. Never having done such documentation, what are aspects of the task I should consider? For example, although various people have enthusiasm about stylish solutions like Marginalia, I’m going for something as close to Javadoc as possible. What other sorts of considerations should be made when deciding on a documentation system, or is the landscape as flat as it looks so far?

Have you considered cljdoc?

Other than automaticity, what are cljdocs advantages?

It’s consistent with all the other clj/cljs documentation, it manages boring stuff like hosting and docs for previous versions for you, it supports articles and examples.

1 Like

I only ever used Codox, and one thing I like is you can use it as a library where it just returns you a kind of doc AST and you can then template that to whatever output you want. So you can make it look the way you want.

1 Like

While I too have used (and like) Codox, I’m increasingly of the opinion that being able to make docs “look the way you want” is an anti-pattern, since the end state for documentation consumers is a shambolic smörgåsbord of different documentation styles, navigation patterns, and wotnot; it’s a classic example of incidental complexity.

This is one of the reasons I’m excited by cljdoc - not only is it turnkey (some of the open source projects I contribute to are on there, and I didn’t even know until just now!), it also provides a level of consistency across independent projects. The fact that they’ve chosen a style different, perhaps, to the one I would have picked, is vastly outweighed by the benefit consumers get by having consistent documentation style and organisation across so many projects.

[edit] I’m primarily referring to public (e.g. open source) projects that have a wide and generally unknown audience. Obviously in walled gardens (corporate repos, etc.) there’s a lot less need to line up with The Universe.

2 Likes

I’d love to answer this in writing and save you the video but I’m a little short on time right now so please consider watching this video in which I try to explain all the features and ideas behind cljdoc:

Happy about suggestions if you have any!

I don’t have any concrete suggestions yet, but I’ll be sure to let you know (do you prefer issues on the GitHub repo if/when I do?).