41–50 of 57 posts
This essay seems to be missing the main primary references for literate programming: https://www.cs.tufts.edu/~nr/cs257/archive/literate-programm... https://www-cs-faculty.stanford.edu/~knuth/lp.html Knuths intention seems clear enough in his own writing: Literate programming is a methodology that combines a programming language with a documentation language, thereby making programs more robust, more portable, more e…
(Having said that, I firmly hold the opinion that we should all be writing READMEs in HTML[2][3] (instead of Markdown) and more fully exploring/exploiting the capabilities—and ubiquity—of web browsers to enable "smart documentation": self-contained (i.e. single-file) study aids, visualization widgets, etc[4].)
1. https://www.teamten.com/lawrence/programming/write-code-top-...>
2. https://hn.algolia.com/?dateRange=all&type=comment&prefix=tr...>
3. https://crussell.ichi.city/pager.app.htm>
4. https://holzer.online/articles/easteregg-lp-style/>
https://backbonejs.org/docs/backbone.html https://github.com/jashkenas/backbone/blob/master/backbone.j... https://ashkenas.com/docco/
Earlier quoted context omitted.
I dream of a world where the Knuth idea of programming and mathematics are naturally embedded in our cultures, like novels are. I find it weird to not be able to find linux source code and commentaries or even math/physics/science masterpieces in libraries where you can find Finnegan's Wake easily (at least where do I live), and not be able to talk about the GHC in between two discussion about romance or the weather…
> I find it weird to not be able to find linux source code and commentaries That one statement is a great concise explanation/motivation for "literate programming". Explanations with code, that explain code design choices, in a way that enables the code to be understood better, and the ideas involved to be picked up and applied flexibly to reading and writing other code. Another way to view it is: Developers are "com…
This essay seems to be missing the main primary references for literate programming: https://www.cs.tufts.edu/~nr/cs257/archive/literate-programm... https://www-cs-faculty.stanford.edu/~knuth/lp.html Knuths intention seems clear enough in his own writing: Literate programming is a methodology that combines a programming language with a documentation language, thereby making programs more robust, more portable, more e…
A good start would be just commenting code! Almost all the code I've looked into recently has been startling - the only comments are the licence boilerplate at the top of each file!
I can think of only one product/library/package that was commented to explain what was happening. Go look at the source for a random package that you depend on. If you're really lucky, there might be something hinting at the meaning of function arguments, but like as not, not even that ;(
From the README "Inform is itself a literate program (written with inweb), one of the largest in the world. This means that a human-readable form of the code is continuously maintained alongside it: see Inform: The Program"
This essay seems to be missing the main primary references for literate programming: https://www.cs.tufts.edu/~nr/cs257/archive/literate-programm... https://www-cs-faculty.stanford.edu/~knuth/lp.html Knuths intention seems clear enough in his own writing: Literate programming is a methodology that combines a programming language with a documentation language, thereby making programs more robust, more portable, more e…
> I chose the name WEB partly because it was one of the few three-letter words of English that hadn’t already been applied to computers. Heh.
Earlier quoted context omitted.
I dream of a world where the Knuth idea of programming and mathematics are naturally embedded in our cultures, like novels are. I find it weird to not be able to find linux source code and commentaries or even math/physics/science masterpieces in libraries where you can find Finnegan's Wake easily (at least where do I live), and not be able to talk about the GHC in between two discussion about romance or the weather…
> I find it weird to not be able to find linux source code and commentaries That one statement is a great concise explanation/motivation for "literate programming". Explanations with code, that explain code design choices, in a way that enables the code to be understood better, and the ideas involved to be picked up and applied flexibly to reading and writing other code. Another way to view it is: Developers are "com…
For something as complex as the Linux kernel, there is no single document that is going to explain the entire system to anyone who reads it. For a start, different people need different levels of explanation. Someone fresh out of a JavaScript bootcamp is going to need a very different guide to Linux than someone who's spent years working on the Windows kernel and just needs to know what's different and what's the same. Moreover, the further a person is from understanding how the Linux kernel works, the more iterative the explanation will need to be: first setting up the broad concepts, then explaining these concepts in more detail, then clarifying these details with more precise examples, and so on. If these layers of explanations are bound to code, then the person who needs less of an explanation will end up skipping parts of the codebase (assuming they let themselves be guided by the literate documentation). If the explanation is not bound to the code, then that's not really literate programming, it's just documentation.
The other issue is that even two different people with similar levels of skill will often want things explained in different ways. Partly, that's going to be things like the analogies they're used to, and partly that's going to be a question of what they need from the explanation. A document "The Linux Kernel for the Data Scientist" will probably look very different from "The Linux Kernel for the Systems Engineer", and both will be different again to "The Linux Kernel for Project Managers". A huge part of technical writing is understanding precisely who your audience is, and in literate programming, your audience kind of becomes "everyone", which is too large an audience. The advantage of separating code and documentation is that you can write your code for a much more restricted set of readers, but provide a bunch of different additional guides that are each aimed more precisely at a target audience.
I think literate programming can work for programs that are primarily intended as tools for teaching (because then the whole application is designed to be read by a specific target audience, and can be written from that perspective), but for general-purpose applications, particularly more complex ones like the Linux kernel, are better served by separating out the different documentation concerns.