Clojurians Log v2

I have been doing some brain storming on how to make more understandable software. I’m trying to turn those ideas into something actionable, maybe a clojure library. The current idea is to give projects more of a narrative. I wrote up a quick proposal of what this might look like here: https://github.com/drewverlee/narrative/blob/master/ideas.md I welcome any feedback. Thanks

So you’re thinking of a library to allow developers to tell a story via code showing users how to user said library?

@drewverlee Have you looked at Marginalia?

I've been using that heavily on a new project I started at work recently and really liked it. I wrote the narrative (as markdown in comments) for the code and then gradually filled in code in among that narrative, turning some narrative comments into docstrings as I wrote the functions (and leaving other parts as comments, since Marginalia incorporates those into the documentation).

I think this concept could be used for both helping with the development story and with the user story. They would probably be different narratives

I look a very brief look at it, I plan on studying it more as the goal is the same.

I think both help to build on the other. I like the idea though. If this is a practice that developers can adapt as part of their early workflow, telling a story of their code, then not only will documentation come more easily and more clearly, but, like you said, so will development. It’s also a great tool for the developers because lacking or poorly formed APIs will show themselves earlier on

Looks very similar to literate programming.

Is there a difference I failed to grasp?

Literate programming is documentation with code embedded and has machinery to reorder/reassemble code -- so narrative takes precedence. Marginalia is very lightweight by comparison and is focused on code that contains documentation, rather than the other way around.

What you're describing in narrative (above) seems very much in line with what Marginalia achieves: annotated code that can produce nice documentation, with code fragments aligned with the relevant pieces of documentation, while also not affecting the code (and not needing any special editor plugins etc).

@seancorfield @dottedmag != @drewverlee 🙂

At most you might want comment-line-folding to reduce the "noise" if you get carried away with inline comments and marginalia.

Actually, I was referring to @drewverlee’s narrative idea when asked about lit. prog.

Yes, @drewverlee replied in a thread saying narrative's goal was the same as Marginalia -- so my response was to you @dottedmag drawing a distinction between literate programming and what Marginalia provides which is what @drewverlee said was the goal of narrative 🙂

So narrative/Marginalia are different to literate programming.

I see, thanks.

I could have been clearer about it 🙂

https://github.com/arrdem/stacks

I personally subscribe more to the narrative style - for my last big project I wound up writing a bunch of documents (design doc, runbook, architecture overviews) all of which I wanted to cross-link and relate to the code.

I think that supporting separate documents mutually referencing docstrings & symbols is far more important than inline commenting. Been playing with some ideas about how to build a sphinx-like that supports that workflow well for Clojure.

(not much in that repo so far, just some doodles at parsing example files for analysis & highlighting)

Stacks sounds like it has a lot more in common with Literate Programming, since it's primarily documentation that you might extract code from?

I'm gathering feedback at this point mainly. I feel like everyone wants interactive, informative docs, so the idea isn't probably novel. Its probably just not worth the cost... But maybe there is some way to help developers incrementally build that up as it becomes more valuable.

Yeah, there's definitely plenty of room for ways to help developers produce better documentation. I've always been very leery of Literate Programming in the large but most of the API Documentation generators are too minimal for the sort of internal documentation I'm interested in...

Stacks is gonna have a fairly strict docs vs code separation. It’ll consume docstrings as one source but my expectation is that the majority of documentation will be written separately.

And that making writing that documentation and linking to the extracted source information is what you should optimize for.