2 ms·
This is an extremely common problem with documentation, it's not limited to these kinds of tools. The fundamental problem is: you understand how something work
by steveklabnik 11y ago
This is an extremely common problem with documentation, it's not limited to these kinds of tools.
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.
- PaulHoule 11y agoIt 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.
- steveklabnik 11y ago> Ever hear of a wiki, or an issue tracking system? ... yes. I didn't say that it was impossible, just that it's a very common issue, more broad than just compiler tooling.
- qwertyuiop924 11y agoWell, 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).