This page is not created by, affiliated with, or supported by Slack Technologies, Inc.
2018-06-09
Channels
- # beginners (47)
- # boot (5)
- # cider (25)
- # cljs-dev (2)
- # clojars (2)
- # clojure (33)
- # clojure-dev (25)
- # clojure-italy (2)
- # clojure-uk (35)
- # clojurescript (27)
- # core-async (2)
- # datomic (5)
- # graphql (2)
- # immutant (3)
- # off-topic (3)
- # onyx (2)
- # pedestal (4)
- # portkey (52)
- # reagent (2)
- # shadow-cljs (55)
- # spacemacs (21)
- # sql (8)
- # tools-deps (22)
for contribs, is there a strong preference for guide-like material to be in a guide rather than in the repo?
The only data I would offer on that question is that http://clojure.org and the guides have a lower barrier-to-entry than the code repos. That was why I moved the java.jdbc
guide material out of the repo (there was no option to move them to the http://clojure.org website back then) -- community members complained they "couldn't" (wouldn't) contribute to the docs because of the CA / JIRA / patch process. I moved them to http://clojure-doc.org and there's no CA, no patches, just plain ol' GitHub and Pull Requests.
Seems like gh wiki satisfies that too
I personally have no strong preference :)
There’s obviously value in having docs be “near” the code
(not that I think a java.jdbc
guide belongs on http://clojure.org 🙂 )
But I could see a test.check
guide on http://clojure.org ...
http://clojure.org doesn't have anything about testing does it?
(other than spec's check
function)
I was aiming to overhaul the test.check docs, and realized I could probably drop a lot of stuff from the repo if I put equivalent/better stuff on http://clojure.org So I think I will aim at that. are there any other contribs with docs on http://clojure.org? I can see the argument that test.check should even if nothing else (but spec?) does
Antora (by the asciidoctor team) has a very nice feature where it "collects" documentation from multiple sources, and builds it into a single one.
the workflow would be that occasionally somebody runs something that causes a commit in clojure-site
with updates from other contrib repos?
@gfredericks Your inquiry does raise an interesting question tho': which contrib libraries are considered "core" enough to be on http://clojure.org? @alexmiller any thoughts on that?
my justification for test.check was that it's softly depended on by clojure; I guess it's unique in that category?
somebody please write a guide on how to decide whether your contrib lib's docs belong in a guide
@gfredericks Other way round, when the clojure-site is next built (either manually or automatically via a trigger from the contrib repo) then clojure-site would "pull" the latest copies of guides from repos.
Totally feasible but not something I would have time to do for a long time. Better to just pick one.
oh so build-time; and it'd only exist in one git repo so they couldn't be out of sync
though now that I think about it, that would subvert the legal purposes of clojure-site
I don’t know what that means. Both are EPL and under same CA
oh then I guess I was only referring to procedural differences
Someone was asking me the other day if the java.jdbc
docs from http://clojure-doc.org could be folded back into the contrib repo -- and I wasn't sure how that could work re: CA.
You would need to have all contributors sign the CA and approve it