Clojurians Log v2

@arrdem link down! 🙂

I just stood the server down so I could use my other laptop 😉 sec.

> Browsing good documentation should be a lot more like browsing the stacks in a library. Search and cross-reference need to be strongly supported and aggressively used.

It’s uh hardly a production deployment

maybe this is obvious, but how do stacks in a library solve the problem of search and cross-reference?

just by physical proximity?

Yeah I’m just alluding to the physical experience of standing in front of a section and being able to peruse it at leisure, or find a section rapidly by some index. Particularly that sort of associative perusal / proximity is difficult to replicate.

@shaunlebron demo server’s back up for a bit.

a startup working on this problem of connecting information by proximity: https://www.ideaflow.io/

> In writing Grimoire, I kept banging back into wanting to write documentation for topics such as destructuring or particular interfaces like sequences which had no logical home in the documentation of a single namespace or var.

i ran into this same problem with the cljs api docs

yeah a huge part of the motivation behind stacks is trying to go articles first, gendocs / source docs second.

i kind of got around it by having pseudo entries under syntax: http://cljs.github.io/api/syntax/#destructure-vector

but it can’t cover everything, like sequences in your example

Yeah. Grimoire did eventually grow an articles capability but it was super second class compared to how the core documentation / data was treated.

looking at demo now

this is your github readme, but served in a special way?

Yep! The ring server is serving the same articles you can see on GH, but rendered via Stacks’ article pipeline. So the doctests and repl sessions are actually all being eval’d when you load the page. None of that output is static content.

syntax higlighting, graphviz etc all done on-demand. which isn’t ideal, you could do much better, but this is an MVP of being able to serve these much more sophisticated documentation embeds.

Places I want to go with this: - Static site generator mode - Ability to cross-link between articles and vars, and from var docstrings to articles (this requires some extended syntax highlighting for docstrings which will be interesting) - Better REPL session management so that sessions persist and can be joined from the web. Eg just click and example and type more forms in after it.

this is neat, a lot of new things to consider and digest I think

example of reference links anywhere on this demo?

> Supports and encourages (due to convenient notation & link checking) the use of references between documents

Sorta hang on.

https://github.com/arrdem/shelving/blob/develop/docs/basic.md

these docs were generated using the script that’s the prototype of those capabilities.

I’ve copy-pasted that script around between a bunch of repos and haven’t really solidified it / integrated it into stacks yet. That’s probably the next thing I’m gonna do, because then I can defend deploying this at work.

ah, links to other files in the docs? I was expecting links to source functions for some reason

https://github.com/arrdem/shelving/blob/develop/src/dev/clj/compile_docs.clj

There’s a lot of things you could do there - again I’m trying to take a bunch of MVP weekend hack sorta stuff and integrate it.

Probably most important is to nail down some remotely acceptable CSS 😉

@arrdem clojure conj talk? 🙂

Maybe. Definitely a SF CLJ talk or three. If I get some work time to really pull this together it could be conj worthy.

Grimoire 4.0, four years late.

I would vote for it, since I’m not in SF!

cool stuff, I’ll keep an eye on it

i like the activity around docs recently (and @martinklepsch’s cljdoc)

thanks man! hopefully it goes somewhere soon-ish, otherwise it’ll probably take another 6mo nap.

work’s suddenly reached the “DOCUMENT ALL THE THINGS ZOMG” stage so I should have a good excuse for this.

❤️ work excuses

seriously

would love commentary on the ideas or even just the markup (markdown) I’m choosing if you get the chance. I know there’s a lot of halfbaked stuff going on here.

I suspect that if I had to choose I’ll back off from the “graph like discovery” thing and focus on this as an article / book editing platform.

because there really isn’t much that even tries to get that right.

not sure how valuable my nitpicks would be

fair

but I’ll schedule some time tomorrow to look again

getting late here, out for the night, just wanted to see why the #docs channel suddenly went bold in the sidebar here 🙂

Heh.

Thanks again! Get some sleep, I’m stuck up waiting for a late night deploy 😕

good luck then

👋

o7