Clojurians Log v2

Hi all - been learning duct, and it’s really cool. But I feel that the beginner resources are a bit lacking, e.g. the guide doesn’t go into much depth about how duct actually works, the duct framework README is a bit terse, the core README is outdated on pretty major concepts (it still describes modules as returning a map with :req and :fn ). There’s also no good resource I could find (aside from scattered talks/blog posts) that serves as a consolidated introduction to duct and integrant. Would there be interest in a short book/longer user guide that goes into more depth and consolidates common duct usage patterns? Or maybe there’s a resource already like this I’m missing?

For a pretty major example, I think I browsed quite a few resources and didn’t ‘get’ that the final Integrant configuration map is created by folding over all the initiated profiles and modules (and that this map is completely separate from the supplied maps in e.g. config.edn) until I actually read the source

The duct framework README almost says this, but it says something like “the original configuration is initiated into an intermediate configuration”, which is confusing because it’s that’s not the same type of initiation that Integrant performs. Integrant initiates the configuration into a series of functions, which then act as middleware producing the final configuration

One guide that's commonly hidden and probably the most up to date is this file https://github.com/duct-framework/docs/blob/master/GUIDE.rst

It doesn't go into detail about how the module system works though

Also, I wrote a small guide on the Duct Base config / Profiles / Modules for my colleagues a while back. I added it to the wiki. Maybe it'll be useful to others: https://github.com/duct-framework/duct/wiki/Configuration#duct-base-profiles-and-modules

However, the duct docs can use a lot of work. It's true that everything is very scattered at the moment. And a lot of outdated. It would be nice to clean everything up and only have a single source of documentation. I don't really have the authority to do that though 🙂

Having been using Duct for a year now, I'd concur with all of this. One area that is sorely lacking in documentation in my view is the Duct merge logic e.g. what effect profiles and the likes of ^:demote, ^:promote, ^:displace , ^:replace have - again, viewing the source helps a lot here but a more holistic view would be great. I've been meaning to create an explain-merge function for a while now. As for the module system, something that helped me understand them was, after viewing the source, realising that they're essentially just "configuration factories" (i.e. components for generating more config).

Another thing that I think would be extremely beneficial is key documentation. Right now if you use one of the duct-framework modules, you need to read the source to know what your options are. Since keywords don't support metadata you can't add docstrings. I was thinking of having something like an integerant_meta.edn file which holds keys + maps as values. e.g.

{:some/key {:doc "documentation for this ig/init-key",,,}}

Most of this is documented in meta-merge, but I agree with you. Also demote / promote isn't part of meta-merge

also duct actually implements its own version of meta-merge

I definitely want docs on keys… though it’s arguably a clojure problem. It seems likely that spec/spec2 will at some point support doc strings… though who knows when that will be. Also I’d like a standardised way to document components, essentially on the defmethod, but that’s obviously a little awkward — not sure if there’s a good solution to this.

Totally agree on the wider issues of duct documentation. I also wonder if having the docs scattered across so many repos/places is useful. It would be useful to have some centralised docs somewhere.

This would be really cool.. one observation is that modules and profiles are used in a different context from most other integrant keys, and I feel a full documentation solution would somehow handle this too. But yeah, if it’s not accepted as a primary solution then I agree there’s not much point

Thanks for all the comments! Seems like many agree more centralized documentation would be helpful. Then I might try to write some open chapters of a duct book/guide, with burden of maintainability on me of course. If it ends up being good enough, then maybe it could be merged into the existing documentation structure. Writing helps me learn, and I already have quite a few notes on how duct works as a starter guide 😛

The only risk is that if it doesn't get merged into the official stream, then we'll have another source of documentation

I don't think that should dissuade you though

Ah yes, the old https://xkcd.com/927/

If it doesn’t get merged, then I’d be happy to mark it as inactive and link to the existing documentation to prevent this

I'd just rebel