Fork me on GitHub
#docs
<
2018-07-10
>
shaunlebron04:07:39

@arrdem link down! šŸ™‚

arrdem04:07:00

I just stood the server down so I could use my other laptop šŸ˜‰ sec.

shaunlebron04:07:06

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

arrdem04:07:07

Itā€™s uh hardly a production deployment

shaunlebron04:07:45

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

shaunlebron04:07:00

just by physical proximity?

arrdem04:07:38

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.

arrdem05:07:18

@shaunlebron demo serverā€™s back up for a bit.

shaunlebron05:07:19

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

shaunlebron05:07:01

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

shaunlebron05:07:24

i ran into this same problem with the cljs api docs

arrdem05:07:42

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

shaunlebron05:07:02

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

shaunlebron05:07:27

but it canā€™t cover everything, like sequences in your example

arrdem05:07:48

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

shaunlebron05:07:35

looking at demo now

shaunlebron05:07:47

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

arrdem05:07:35

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.

arrdem05:07:21

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.

arrdem05:07:55

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.

shaunlebron05:07:56

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

shaunlebron05:07:10

example of reference links anywhere on this demo?

shaunlebron05:07:20

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

arrdem05:07:28

Sorta hang on.

arrdem05:07:00

these docs were generated using the script thatā€™s the prototype of those capabilities.

arrdem05:07:34

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.

shaunlebron05:07:42

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

arrdem05:07:23

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.

arrdem05:07:46

Probably most important is to nail down some remotely acceptable CSS šŸ˜‰

shaunlebron05:07:31

@arrdem clojure conj talk? šŸ™‚

arrdem05:07:55

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

arrdem05:07:02

Grimoire 4.0, four years late.

shaunlebron05:07:55

I would vote for it, since Iā€™m not in SF!

shaunlebron05:07:20

cool stuff, Iā€™ll keep an eye on it

shaunlebron05:07:03

i like the activity around docs recently (and @martinklepschā€™s cljdoc)

arrdem05:07:09

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

arrdem05:07:27

workā€™s suddenly reached the ā€œDOCUMENT ALL THE THINGS ZOMGā€ stage so I should have a good excuse for this.

shaunlebron05:07:28

ā¤ļø work excuses

arrdem05:07:11

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.

arrdem05:07:40

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.

arrdem05:07:01

because there really isnā€™t much that even tries to get that right.

shaunlebron05:07:02

not sure how valuable my nitpicks would be

shaunlebron05:07:20

but Iā€™ll schedule some time tomorrow to look again

shaunlebron05:07:10

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

arrdem05:07:06

Thanks again! Get some sleep, Iā€™m stuck up waiting for a late night deploy šŸ˜•

shaunlebron05:07:58

good luck then