Fork me on GitHub
#clojure-dev
<
2018-06-09
>
gfredericks21:06:22

for contribs, is there a strong preference for guide-like material to be in a guide rather than in the repo?

seancorfield21:06:30

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.

alexmiller21:06:19

Seems like gh wiki satisfies that too

alexmiller21:06:57

I personally have no strong preference :)

alexmiller21:06:32

There’s obviously value in having docs be “near” the code

seancorfield21:06:43

(not that I think a java.jdbc guide belongs on http://clojure.org 🙂 )

seancorfield21:06:59

But I could see a test.check guide on http://clojure.org ...

seancorfield21:06:40

http://clojure.org doesn't have anything about testing does it?

seancorfield21:06:19

(other than spec's check function)

gfredericks21:06:50

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

dominicm21:06:02

Antora (by the asciidoctor team) has a very nice feature where it "collects" documentation from multiple sources, and builds it into a single one.

dominicm21:06:40

I imagine something like this could happen by using tools.gitlib perhaps?

gfredericks21:06:51

the workflow would be that occasionally somebody runs something that causes a commit in clojure-site with updates from other contrib repos?

seancorfield22:06:54

@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?

gfredericks22:06:42

my justification for test.check was that it's softly depended on by clojure; I guess it's unique in that category?

alexmiller22:06:05

I’d be happy to have guides on anything

😂 4
gfredericks22:06:30

somebody please write a guide on how to decide whether your contrib lib's docs belong in a guide

4
dominicm22:06:54

@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.

alexmiller01:06:29

Totally feasible but not something I would have time to do for a long time. Better to just pick one.

gfredericks22:06:44

oh so build-time; and it'd only exist in one git repo so they couldn't be out of sync

gfredericks22:06:05

though now that I think about it, that would subvert the legal purposes of clojure-site

alexmiller01:06:29

I don’t know what that means. Both are EPL and under same CA

gfredericks01:06:16

oh then I guess I was only referring to procedural differences

seancorfield22:06:21

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.

alexmiller01:06:16

You would need to have all contributors sign the CA and approve it