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