This page is not created by, affiliated with, or supported by Slack Technologies, Inc.
2018-07-10
Channels
- # beginners (50)
- # cider (112)
- # cljs-dev (7)
- # clojure (34)
- # clojure-brasil (1)
- # clojure-greece (4)
- # clojure-italy (8)
- # clojure-nl (14)
- # clojure-russia (4)
- # clojure-uk (94)
- # clojurescript (96)
- # clojutre (5)
- # cloverage (1)
- # cursive (5)
- # datomic (59)
- # docs (53)
- # figwheel (4)
- # fulcro (1)
- # hoplon (1)
- # hyperfiddle (3)
- # jobs (3)
- # luminus (6)
- # nyc (3)
- # off-topic (9)
- # onyx (3)
- # overtone (4)
- # re-frame (2)
- # reagent (16)
- # reitit (9)
- # ring (2)
- # ring-swagger (1)
- # rum (1)
- # shadow-cljs (81)
- # spacemacs (14)
- # specter (12)
- # sql (1)
- # tools-deps (2)
- # vim (110)
@arrdem link down! š
> 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.
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
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
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.
@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.
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
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.
not sure how valuable my nitpicks would be
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 š
good luck then