docs 2018-05-24 | Slack Archive

Drew Verlee18:05:57

@martinklepsch This is super cool and looks like a big improvement over some existing similar solutions. I wonder if it would be possible to expand this to encourage projects to have more of a narrative. One that could be expanded or modified by the community. By narrative, i mean that the project tells you a story about how its used. I feel like right now the readme mainly serves this purpose, but its static and isn’t tied to the code. So the two things i feel could be improved are making this narrative a) interactive b) tied to the code c) leverages tests (property based or unit) to walk you through the code base. I feel projects like https://www.maria.cloud are similar to this type of approach. Of course, some projects are hard to run in a browser because of their dependencies, which i feel might be a commentary on how they were built, but i’m sure the situation is unavoidable or not worth the effort in many cases.

martinklepsch20:05:02

interactive examples are definitely something I’d like to see explored but I’m afraid it might only ever work well with functions that operate on plain data

Drew Verlee23:05:08

Thats very interesting, because maybe we should all design so that the majority of our code operates in plain data

martinklepsch06:05:32

Yeah, I’d go with that and probably there’s pure functions in various libs... right now I’m thinking that examples to copy and paste might be sufficiently good as a first step?

Drew Verlee12:05:51

Its a great first step. In my previous comment i was just explaining that as system creators, we stand to gain much by making the core of our system pure. In this case, if you have isolated all your logic into pure functions, and your lucky enough that code is clojurescript compatible, then it would be a lot easier for tools (like yours) to do something with it.

Drew Verlee19:05:40

tried it with my little library. All good but got an error, not sure if its something i need to fix on my end or if i should file an issue: https://cljdoc.xyz/d/fk-gen/fk-gen/0.3.3-alpha/api/fk-gen.core

martinklepsch20:05:30

interesting, can you open an issue with that link so I don’t forget to look into it at some point?

Drew Verlee19:05:07

I just saw the bit about articles, thats a good addition. This is actually really nice little time saver and sets a good convention for creating examples.

martinklepsch21:05:21

There’s a #cljdoc channel as well btw @drewverlee

2018-05-24

Channels