It can happen.
Ever hear of a wiki, or an issue tracking system?
Literate programming systems have failed so far because a "code-document" bundle is not the way.
The way is to attach whatever documentation exists to a scaffolding that includes the code. For instance, stackoverflow contains a large amount of documentation which is poorly organized and is only findable (sorta kinda) because Google is (still) a good search engine.
Re:Rich Programmer Food (2007)
by steveklabnik on Monday May 23, 2016 @01:26PM
(#11755326)
> Ever hear of a wiki, or an issue tracking system?
I didn't say that it was impossible, just that it's a very common issue, more broad than just compiler tooling.
Re:Rich Programmer Food (2007)
by qwertyuiop924 on Tuesday May 24, 2016 @08:58AM
(#11761154)
Well, yeah. but compiler tooling has it far worse than most things. And I was reading through the docs to some compiler tooling written in scheme. Shudders. It has a Lex/YACC like grammar DSL, but it doesn't explain the syntax, just provides a fairly bad example. And this was (chibi parse), which was written by Alex Shinn, who usually does pretty GOOD documentation (irregex in particular is excellent, assuming you already know regex).
The fundamental problem is: you understand how something works, and you are trying to communicate with someone who doesn't. In a conversation, your partner can ask clarifying questions when you accidentally say something that's not clear, but in text, you're separated by time and space. So this can't happen.