
The Garden and the Stream: A Technopastoral - pragmar
http://hapgood.us/2015/10/17/the-garden-and-the-stream-a-technopastoral/
======
mikekchar
It's a bit long an rambly, so it's hard to get a good picture of what the
author is trying to say. However, I think I have experienced some similar
feelings lately. I've been trying to write some literate coffeescript and one
of the problems I was running into is that it is just a PITA to edit. You've
got this huge block of text that you have to jump around every time you want
to edit anything.

So, I got the idea to factor it, like the program that it is, and add links
all over the place. That way, if you want to view the explanation you can, but
you don't have to. Also, I don't have to wade through the documentation every
time I'm looking to make a change.

And then I started to think, "How are people going to read this?" One of the
ideas of literate programming is that you "weave" the human representation in
a way that is best for the human to understand. But now I have a hypertext
document, which allows the reader to "weave" their own path through the
code/explanation.

Furthermore, because I realized that not everyone will take the same path
through the code, I started to reuse links in many different places. You can't
assume that someone has seen something, since there is no narrative any more.
You have to make a network that is sensible from any "angle".

I think this is very similar to the "garden" he describes.

Interestingly, because some of my colleagues are very opinionated I started
worrying about some of the code. I really thought that some of the things I
was doing were "good ideas" (tm), but I was aware that there were some smart
people with whom I work who would undoubtedly disagree. Without the narrative,
how do I invite discussion?

We have a culture of code reviews on our team and one of the things we value
are small pull requests very frequently. Especially if you have something
potentially controversial, the idea is to post a quick PR and get feedback
right away. Personally, I also invite people to submit counter PRs that
describe their ideas in code.

Now, this literate project of mine is a personal project, so I don't have the
luxury of a captive audience. How do I attract people? I actually sent around
tweet sized emails to a few people with links to my code and said, "What do
you think about this? Do you agree with the explanation? Do you have other
ideas?"

This seems to me to be very similar to the "stream" concept that the author
has. However, all of this activity is really time consuming and labour
intensive (especially making all the links and keeping them up to date!!!). I
think there is definitely some value to these ideas, but I need better tools
;-)

~~~
pragmar
My team's been using a project management tool to document dark corners and
eccentricities within our systems. It sort of works as a searchable DB of
notes, and the more I contribute, the more I get the same "who's ever going to
read this" feeling. We've also experimented with wiki. I'm not sure what the
solution is to contextualizing knowledge, but it certainly feels like the
tools available are in their infancy.

