I'd say there's a mission criticality spectrum, and a type strictness spectrum Whether both go hand in hand depends on whom you ask 🙃

I agree with vemv except I'd describe the second not specifically about types but about locked-down-ed-ness, so it includes use of records, contracts, specifications, verification, or even versioning, docs, and test coverage. I don't have a specific name for this, but I think about it in degrees of dynamicism or concretization, or in infrastructure terms (to extend Rich's "guardrails" analogy).

Specification can be a good term (as all those mechanisms, in a way, are about removing ambiguity)

Maybe the specific tools used to move towards the goals I'm looking to name are less interesting.

Correct vs expressive feels almost right, but not really

I've seen it labeled "Software quality" or "maturity" on a diagram, which I don't mind even as an advocate of the dynamic end.

Correctness is definitely orthogonal - you always want correctness

Ditto quality (mostly)

I think level of specification is probably the spectrum in Clojure world. If you think wider, people are really talking about proof

As a razor there, do you believe ambiguity is a weakness or a tool?

If I could make an attempt at narrowing it down further, it's level of formal specification, which in this context means formal methods could be applied to it In theory, it's great, at least until you get the specification wrong, which is very likely

I value flexibility towards future changing requirements far more than proof

Exactly. The best proof of requirements satisfied is not worth much once requirements have changed 🙂

I have some metaphor in my head that the difference is along the lines of crossing a river with a boat, or by using a reinforced concrete bridge. 🙂

Changing your destination is a little bit easier with the boat.

The bridgeness vs boatness dimension.

I can't help thinking, if your program is composed of e.g. 2000 discrete, 'atomic' functions, they can be fully specified, but if you need to refactor, you can easily discard them individually by simple deletion and rearrangement Same for deftests, you can delete them if their atomic counterpart is no longer needed Similarly, Spec/Malli specs are particularly DRY, you define what an ::age is, instead of repeating Int all over the place. That also is agile, i.e. can easily be readapted to changing requirements tldr applying the right ideas one can have it all 🙂 some peers in the Clojure world easily see this, other times I wasn't as lucky.

Rigidity

Yeah I like rigidity!

clojuredocs is a third party offering. it’s very helpful. it’s user annotated. I don’t know what clojure-doc is. The guides and reference material on the official Clojure website are official guides and references by the authors and maintainers of the Clojure language.

http://Clojure.org is the central place to go start learning and is maintained by the team that manages Clojure itself. Everything else is community created and usually linked from the https://clojure.org/community/resources. many things have evolved over the last 16 years. I assume people create things that are felt needed. I am also 'guilty' of creating my own learning resources at http://practical.li

http://clojuredocs.org (“Community-Powered Clojure Documentation”) is a wonderful resource. Many great examples for each function!

the fragmentation isn't due to a single entity choosing to fragment docs, instead it's a product of different people wanting to create different resources

a diversity of tactics in teaching is a good thing, it's great that so many people want to share and teach 💜

There are also many ways to get help, although the Clojure team itself does so Via http://ask.clojure.org Here is an overview of the ways to ask for help https://practical.li/blog/posts/cloure-community-getting-help/

And my favorite “frontend” for Clojuredocs: https://jafingerhut.github.io/cheatsheet/clojuredocs/cheatsheet-tiptip-cdocs-summary.html

https://clojure-doc.org/articles/about/ explains why it exists and what it covers (and does not cover). When I initially resurrected it, there was a lot of duplication with http://clojure.org because that content hasn't used to be on http://clojure.org - the official site has improved a lot in the last decade. I've spent a lot of this year editing, rewriting, and expanding the http://clojure-doc.org material (funded by Clojurists Together) so that it is a) up to date and b) offers material you won't find elsewhere (for three most part).

> Is there a reason for this kind of fragmentation? it’s super obvious in other domains. Toyota has an official page for the Camry. That doesn’t stop people making their own reviews about the Camry. And there’s no reason to host the 3rd party reviews on Toyota’s official site

In particular, http://clojure.org is not going to cover community libraries - just official/core stuff - whereas the long form http://clojure-doc.org articles do cover community libraries (see the recently contributed date/time cookbook).

I'm just thinking in terms of something like Python's website, or say Rails. The material there is quite comprehensive. Of course, there are other community resources that add additional info or the same info presented in a different way; there's plenty of value in that. The comprehensiveness of the "official" source is really good as a reference or for beginners though, because I find it where I'd naturally expect to find it. If there's significant effort spent by community members to improve reference material for Clojure, it just seems best bang for buck would be to work together on the "central" stuff where it's lacking and having supplementary stuff elsewhere (courses, books, alternative tutorials, whatever). Again: other languages and big name fwks have this, so it's not a crazy thing to think should exist. I will say that there's been amazing work done all around. The quality and coverage of the Clojure documentation across these sources has improved considerably from when I first looked years back. Massive kudos to all involved 👍

@U11BV7MTK following your analogy, my curiosity is around why I can't find all the details about a Camry on the Toyota website and instead have to hit up the popular community Toyota site to fill in the blanks

And mainly I guess the curiosity is around the contribution process. Like is there a particular reason that makes it so that someone keen to write a guide would choose to put it on clojure-doc rather than official Clojure? If the guide includes third party libraries, that would be a good reason to not include it on official. Is there anything beyond that?

That's pretty much it. http://clojure.org covers core and contrib stuff (everything under http://github.com/clojure) and links to community resources -- but doesn't cover how to use community libraries/tooling at all. And that's a deliberate choice: http://clojure.org isn't meant to be the "fount of all knowledge" but it is intended to be the "official" starting off point.

Also, to contribute to http://github.com/clojure/clojure-site (the repo behind http://clojure.org), you need to have signed the CLA. To contribute to the community sites, you mostly just need a GitHub account 🙂

> why I can't find all the details about a Camry on the Toyota website Toyota isn't going to tell you about "hacks" to improve the car or after-market add-ons.

Another difference is that the bar for quality and review is quite a bit higher on http://clojure.org, because nothing appears there unless it is reviewed by someone on the Clojure team. Getting something added to http://clojuredocs.org is as simple as creating a free account and clicking the "edit" button, typing, and clicking save.

There is limited bandwidth for reviewing and approving things added to http://clojure.org

I find this thread very informative. Summarizing: • http://clojure.org: core stuff (API, tutorials) without examples • http://clojuredocs.org: core API + community produced examples • http://clojure-doc.org: articles about libs, tools, cookbooks Is this accurate?

That's a pretty good 3-bullet summary IMO, yes.

Although the latter has a fairly large "Language" section, for the rest of it, it tries to avoid duplicating content that is elsewhere -- and links to it instead.

BTW, I just issued a PR for incluing a link to clojure-doc in http://clojuredocs.org intro page 😀

> Although the latter has a fairly large "Language" section > This was what got me wondering about it. It sounds like this is mostly historical baggage though, and the current effort is for clojure-doc to add value above and beyond the core docs on the official site which have been getting more and more thorough

friction of contribution and changes in presentation are surely part of the drivers of the fragmentation

Yeah. So far, my work on the language section has just been to update it to Clojure 1.11 (from 1.5!) and make sure the examples run and the output is correct. I have not yet had the time (or energy!) to review it section-by-section against what's on http://clojure.org and decide what should just be excised and linked instead 😐

> friction of contribution and changes in presentation are surely part of the drivers of the fragmentation When http://clojure-doc.org was created (2012), it was hard to get http://clojure.org changed -- and http://clojure.org's content was pretty minimal. http://clojure-doc.org was intended to be easy to contribute to and the hope was that many community members would write tutorials and guides. In reality, only a handful of people contributed to it and then it stopped getting updated... and eventually the server it was hosted on was essentially "lost"... Since I've been actively working on it this year, several people have contributed new sections and the community at large has contributed a lot of helpful feedback. Over time, I hope to reduce the remaining overlaps and make it a good hub for community-contributed tutorials and cookbooks (primarily) on any and all community libraries and tooling that folks want to contribute, where it can add value over and above the original libraries' and tooling's docs.

I was also talking about posting examples on http://clojuredocs.org -- community-submitted examples are so much easier to contribute and are allowed to be more imperfect than an official site

the needs are different for the different sites and materials involved, different levels of effort to contribute, hence fragmentation

none of this is a judgement on any process or site, just an observation that you get different kinds of content with different processes