Clojurians Log v2

@jean.boudet11 / @jasonjckn here's an example using Clerk for a "code explanation" use case, which I published a few days ago: https://neuroning.com/boardgames-exercise/notebooks/walkthrough/ meant as a teaching exercise, so it might be far for your more realistic use cases... Just hoping it might give you some ideas

@kloud Wow dino doc looks very promising. Definitely some ui polishing to do, but the examples are really looking good.

Really impressive ‘documentation’ ty!

We've used Marginalia a bit when creating a new app -- wrote it all up in detailed prose and then just starting converting bits to actual runnable code. There are still some big chunks of docs in that codebase but gradually bits have drifted out of sync with the code -- which is always a problem when you have both code and docs in my opinion. Generally, we just have a README for each app, that is pretty high-level, and try to avoid "separate" documentation. We use docstrings heavily -- in interface to describe how to use a function (and a bit of what it does), and in impl to describe how it does it (if non-obvious) and why it does it that way (again, if non-obvious). Otherwise, we just try to use descriptive names for everything, and rely on editor navigation through the code (via REPL and LSP support).

We also have higher-levels docs in Confluence that describe stuff like how to set up a dev env, how deployment works, where stuff is deployed in staging and production. If run into anything non-obvious in operations, it goes in Confluence.

Thanks @seancorfield 👍

I am working on a documentation generator https://github.com/dundalek/dinodoc which combines markdown readmes and articles with API docs into a single website. It supports multiple source directories within one repo which should cover Polylith structure of projects/components. Currently one needs to specify directories semi-manually by listing them like https://github.com/dundalek/dinodoc/blob/2eeb18e631a75a123262b3a28d779b2dd0500844/examples/polylith/doc.clj#L15-L18. When I find time I am thinking of experimenting to create some integration/preset that could use the Polylith structure automatically. It would probably be also possible to generate and embed some architecture diagrams based on project/component dependencies.

Thanks @kloud I will take a look of Dinadoc!

@jean.boudet11 i'm interested in clerk, but never got around to trying it, lmk if you do / how well it works with polylith.

I would like to say we have README.md in each components directory, but the reality is not so nice..

definitely docstrings go a long way.

> README.md in each components directory That doesn't sound very scalable... we have 160 components... and why not put that information in the ns form, so it's more easily accessible via the REPL and tooling?