Fork me on GitHub
#off-topic
<
2023-05-30
>
Bobbi Towers07:05:58

I'm looking for examples of interactive docs. One that I know of is https://github.com/oakes/Dynadoc Does anyone know of any others? I'm going to be speaking about it on a podcast, so it would be great if I had some good ones to mention.

Bobbi Towers07:05:31

It's part of a kind of grand vision I have to change the way we relate to documentation

Robert Todea07:05:36

Is this related to Clojure only? For example, when talking about UI components, we have StoryBook: https://storybook.js.org/showcase, (e.g. https://react95.github.io/React95/?path=/story/all--all)

Bobbi Towers07:05:00

Ah, that's a good one! No not limited to Clojure, actually that's part of why I was looking for other examples

Robert Todea07:05:12

There is also literate programming, a.k.a. notebooks: https://github.com/nextjournal/clerk for Clojure, and Jupyter: https://github.com/markusschanta/awesome-jupyter. Also https://observablehq.com/plot/what-is-plot. You can fork the examples and play with them in a browser environment.

❤️ 2
Robert Todea07:05:24

Stripe has a pretty awesome documentation. Integration with Stripe Shell where you can try out different scenarios: https://stripe.com/docs/checkout/quickstart This is a blog post from their team about their documentation: https://stripe.com/blog/markdoc

❤️ 2
Bobbi Towers08:05:46

wow markdoc looks really cool 🔥

teodorlu09:05:23

I think Matt Huebert's documentation for his inside-out library is a great example of what's possible: https://inside-out.matt.is/

teodorlu09:05:00

See also Sam Ritchie's work, for example Mafs.cljs: https://mafs.mentat.org/ Sam's usually quite helpful in #mentat-collective 🙂

Bobbi Towers09:05:05

ah yeah, he's really pushing the limits of Clerk!

yes 2
Ben Sless09:05:34

Unison language

Bobbi Towers09:05:45

oh interesting... I work with someone from the unison team

Ben Sless09:05:30

a. That's awesome b. Tons of good ideas there worth *borrowing

ehernacki10:05:17

Speaking of Jupyter-alike tools, the Elixir folks are doing a great work with https://livebook.dev/

flowthing10:05:47

If half-baked things no one’s ever used count, I made this thing years ago: https://github.com/eerohele/useless You can point it to a Markdown or an Asciidoc file with Clojure code blocks, and it makes them interactive and editable. I still think it’s a pretty interesting idea, and it might mix well with the new add lib thing in Clojure 1.12, but I dunno. Not sure if it’s actually useful or just kinda fun (hence the name), I guess.

😻 2
Daniel Craig13:05:02

Re-com’s documentation is interactive https://re-com.day8.com.au

Ben Sless14:05:57

I remember now seeing some Clojure project on gitlab

Ben Sless15:05:55

it used metadata to do interesting things, especially around docs, anyone remember?

flowthing16:05:24

https://gitlab.com/glossa/metazoa comes to mind, but that doesn’t exactly match the description.

Ben Sless16:05:11

Yeah that's the one I was probably misremembering, I thought of building something unison like on top of it

mauricio.szabo18:05:22

I have a dream project where one asks some code to generate documentation, and comments / docstrings get inserted as doc - so far, the same thing that everyone does. But I also want to add testcases as part of the documentation, under "example cases" - that you need people to write good tests, so people could actually use them as docs. Finally, I want to also add some "approval" process with git integration - basically, when it generates the doc, it gets the diff from the previous generated version, and identifies functions/methods that changed, prompting a confirmation: "is this doc still up-to-date with the latest changes?"

6
Ben Sless18:05:57

Why generate static doc? Serve it live (like Unison does)

Ben Sless18:05:45

Docs are metadata attached to packages or functions, tests and examples are metadata attached to functions, and docs can refer to all of them and render in a web UI or text form in the terminal

Bobbi Towers03:06:19

oh that is dope 😍 oh yeah, I remember the parinfer docs

Bobbi Towers03:06:31

loving all the responses!

respatialized16:05:25

https://arxiv.org/pdf/1707.03751 Really wish this proposed convention for hexadecimal notation had caught on; it is very easy to understand and maps directly on to the binary representation of the digits.

Noah Bogart17:05:40

that's pretty nifty

andy.fingerhut17:05:52

Interesting. Seems easy to get some of the digits mixed up if hand-written in slightly-off from ideal position marks, whereas 0-9 a-f are more visually distinct.

Travis Jefferson18:05:49

what if ticks alternated on either side of the main stem?

Igor Garcia19:05:17

So on the proposed new notation: • 7 is 3 • E is F • F is E a bit confusing, no?

Igor Garcia19:05:02

"Names of proposed numerals could also be binary-encoding, such as what was proposed by Robert Laponte [3]: Ho, Ha, He, Hi, Bo, Ba, Be, Bi, Ko, Ka, Ke, Ki, Do, Da, De, Di. For base-256 digits names are joined in two syllable words such as: Hoha, Hehi, Boba, Bebi, Koka, Keki, Doda, Dedi. I" I'd avoid pronouncing those syllables, afraid of opening some gate to Hell and releasing evil demons. HOHA! KOKA!

😂 10
Samuel Ludwig18:05:28

just want to complain about an absolutely astounding MySQL behavior I recently experienced: We're doing a typical mysqldump, to move some data to another remote database a mysqldump will output the create statements for each table, along with insert statements for the data to be inserted into that table. I'm not sure how it works in the normal SQL world, but in mysql, multi-row inserts can be done in two ways (when you're providing a value for every non-calculated column):

Approach 1: Explicitly specify the order of the columns that the value-tuples are in (this can be especially useful if you are providing values in an order other than the order the columns were added to the table).

INSERT INTO mytable ->(col3, col1, col2)<- VALUES (val_for_col3, val_for_col1, val_for_col2)...;

Approach 2: Don't specify the order of the columns, and make sure you provide the value-tuples in the order the columns were added to the table.

INSERT INTO mytable ->_nothing-here_<- VALUES (val_for_col1, val_for_col2, vol_for_col3)...;
For some reason, mysql opted for eschewing the specific column-ordering, and then subsequently gave the column-values in the wrong order!
INSERT INTO mytable VALUES (val_for_col3, val_for_col2, vol_for_col1)...;
This obviously causes the import to fail. :^/ After adding the specific column-order myself, the import works 🙃

mauricio.szabo18:05:49

MySQL is a source of trouble, honestly. I still get mad when I see how popular it became, while at the same time being one of the worst SQL databases I ever worked with. An "interesting" example - there is some connection error that just reads as "MySQL Server has gone away". This happens on some Ruby, Python, and Node drivers, don't know if it's already fixed (I think the JDBC driver fixed this issue). This error commits* transactions!

👀 2
practicalli-johnny18:05:41

Personally I would not use MySql for any commercial projects, given the choice. We don't always have that choice though MariaDB is far better replacement for MySQL according to the people who created MySQL in the first place.

Mno07:05:17

Fun fact, mysql Aurora (the only thing worse than mysql plain in my very humble opinion) has an information schema about tables that has a row count.. That row count can be up to 50% wrong. (as per the docs I could find last time I checked, and as long as it's running on innodb or is am, I can't remember which)

Mno07:05:45

https://dev.mysql.com/doc/refman/5.7/en/information-schema-tables-table.html It was innodb 40 to 50%, apparently it's a general mysql thing but 5.7 is old now (unless you use Aurora)