3 ms·

Perhaps I came across as too critical, I have a lot of respect for what you did and for the craft of technical writing. And I definitely understand that writing

Perhaps I came across as too critical, I have a lot of respect for what you did and for the craft of technical writing. And I definitely understand that writing is not done linearly and is very iterative. Correct me if I'm wrong, but it sounds like you were documenting existing code and that the result was very valuable as documentation, but not necessarily as code. You were acting as a technical writer not a programmer, it's a bit of a disconnect to call it Literate Programming, even if you were using Literate Programming tooling (NoWeb). This kind of documentation is common practice all over industry and it is valued, but I don't think Literate Programming is considered to be widely adopted because of that.

llm_trw 2y ago
I'm having a hard time even understanding what the question is here. You seem to be confusing the tools with the work being done. You can write a prototype of a C function in Python to see if you understand the requirements before you commit to the much harder task of writing it in C. That doesn't mean you're not writing a C program. The same is true for literate programming. I can write code outside the main literate program when I'm not sure it's meant to do before I put it back in.
- oersted 2y ago
  What I'm saying is simply that as you describe it, you are first writing the code normally, and then separately writing some documentation about it accompanied by code snippets for context. But if that's Literate Programming then everyone is doing it and it's not a very meaningful label, it's just documentation. I do get it, the distinction is that you are using NoWeb and you can convert between the documentation and the code, and that the documentation contains the entirety of the code. I suppose that's neat. At some point, this boils down to a pointless discussion of semantics (my fault). "Literate Programming" as you describe it does not sound like a style of "Programming". Actually, when you reverse the Programming/Writing emphasis, it simply becomes "Technical Writing", which is what everyone does, because that's what's actually needed. And it is done by great writers rather than great programmers (which may describe Knuth, with the upmost respect). I always interpreted it as writing the text and the code together, logging your thought process, thinking of code like a piece of literature as it is written, rather than adding some documentation to it later. The notion that writing it like this will yield better code, regardless of its value as documentation. I suppose that's why it was unproductive for me, it is a rather romantic interpretation (again, my fault).
  - llm_trw 2y ago
    You write it however you want. I don't know how you code, but the first draft of code is never what ends up in the code base. Neither is the first draft of the documentation. You can write both together, but until you have an idea of what the structure of the code would look like, and how to split it up then you're better off doing multiple drafts. As always code is read much more often than it is written and literate programming is used for the reading part, not the writing part. The efficiency comes in not having to guess what 0x5F3759DF is there for.

llm_trw 2y ago

I'm having a hard time even understanding what the question is here. You seem to be confusing the tools with the work being done. You can write a prototype of a C function in Python to see if you understand the requirements before you commit to the much harder task of writing it in C. That doesn't mean you're not writing a C program. The same is true for literate programming. I can write code outside the main literate program when I'm not sure it's meant to do before I put it back in.

oersted 2y ago
What I'm saying is simply that as you describe it, you are first writing the code normally, and then separately writing some documentation about it accompanied by code snippets for context. But if that's Literate Programming then everyone is doing it and it's not a very meaningful label, it's just documentation. I do get it, the distinction is that you are using NoWeb and you can convert between the documentation and the code, and that the documentation contains the entirety of the code. I suppose that's neat. At some point, this boils down to a pointless discussion of semantics (my fault). "Literate Programming" as you describe it does not sound like a style of "Programming". Actually, when you reverse the Programming/Writing emphasis, it simply becomes "Technical Writing", which is what everyone does, because that's what's actually needed. And it is done by great writers rather than great programmers (which may describe Knuth, with the upmost respect). I always interpreted it as writing the text and the code together, logging your thought process, thinking of code like a piece of literature as it is written, rather than adding some documentation to it later. The notion that writing it like this will yield better code, regardless of its value as documentation. I suppose that's why it was unproductive for me, it is a rather romantic interpretation (again, my fault).
- llm_trw 2y ago
  You write it however you want. I don't know how you code, but the first draft of code is never what ends up in the code base. Neither is the first draft of the documentation. You can write both together, but until you have an idea of what the structure of the code would look like, and how to split it up then you're better off doing multiple drafts. As always code is read much more often than it is written and literate programming is used for the reading part, not the writing part. The efficiency comes in not having to guess what 0x5F3759DF is there for.