Creating a central documentation repository / website, codox complications

[martinklepsch]

@arrdem

As @plexus already noted, it’d be pretty trivial to steal compute resources from clojars if there’s an execution model – java bitcoin miner and all that. Coming up with a standard for how documentation is built and distributed as a static file format solves that entire problem.

I agree that “stealing compute” is an issue but as someone pointed out it’s a solvable one. Containers, Faas, etc could be solutions. I believe it is critically important that a user does not have to do anything to get some documentation. In my personal experience just having some documentation is a great incentive to make it better.

@arrdem

There’s already some work in this area. For Grimoire, I developed a Maven-inspired store structure for documentation, notes and examples – lib-grimoire. Later, a GSoC student I was mentoring came up with a related specification – lib-grenada.

Those libraries look great and I will need to look more into how we might utilize them. I believe there is significant value in providing machine & human-readable documentation.

@arrdem

While Codox supports articles, all the uses I’ve seen treat it like Javadoc which makes this same assumption that gendocs are sufficient.

While this doesn’t address the issue of cross-referencing in documentation I believe this can (to some degree) be solved by providing “template files”, i.e. sections and files that give some inspiration to a library author what kind of documentation should be present. If they ignore it the “template” info will show up on in their documentation, at which point they hopefully reconsider their choice not to provide any non-API docs.

One issue with these kinds of template files is that something needs to put them into their project tree.

---

I’d really like to get something basic up and running while maintaining some openness to future improvements.

Some other related or not so related links:

• https://docusaurus.io/ may also be interesting to check out for inspiration. Mostly focuses on non-API docs as far as I can see.
• graphql.github.io/notes/NewSiteArchitecture.md at source · graphql/graphql.github.io · GitHub How the GraphQL project structures their site, maybe we can take some inspiration from there for our documentation “template”.