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?
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.
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.
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.
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:
I haven’t used any of the Clojure tools for this but I’ve been dipping an occasional toe in the water of markup languages for decades: DEC Runoff (a clone of Unix roff, I think), LaTeX, DocBook XML, DITA and of course Markdown. Some of these failed but I think the desired objective is to separate ‘content & structure’ - the responsibiity of author and editor roles) from ‘presentation’, decided by house style, the printer or front-end designers. So, I agree that getting involved in the style design while writing is an anti-pattern. DITA allows documents to be built from components, so a piece of text might appear in more than one document or web page, with different styling.
I too have some experience with DITA (I worked in content management for a decade and a half, though only about a third of that intersected with DITA) and a common problem I’ve seen is that it’s just too complex for non-technical authors.
This is in large part due to the lack of a simple straightforward editing tool that lets a subject matter expert capture their knowledge without being exposed to the underlying complexities (and strengths) of DITA. In practice, teams seemed to end up with SMEs using their preferred editing tool of choice (Word, Google Docs, etc.), then a human editor who’s also a DITA technical expert, mogrifies and merges that with their DITA corpus. That’s a pretty heavyweight (too overweight, I’d argue) workflow for most content, including (imho) API docs for libraries / services.
I’ve only read about DITA, after trying to use components in DocBook and failing. It was another format option in the tool we used.
What I was trying to say was that authors should be saying ‘this is the heading of the next section, at a level down’ (though you usually get absolute rather than relative level tags) rather than ‘I want this in 16 point, bold’
I’m always amazed how much pain word-processor users will put up with in manually positioning objects on the page rather than learn the half-dozen tags that would meet their needs, or even learn to use MS Word styles better.
Agreed 100%. I feel like back in the day there was at least some understanding of, and attempts to impose, locked-down templates in tools like MS Word and PowerPoint, but that doesn’t seem to be a thing any more.
Certainly my first “real” job (circa 1990) had strict rules around use of formatting in MS Word (for MS-DOS!) - going outside the template was a sure fire way to get a stern talking to by a manager. Especially if it was a cover letter for a TPS report.
