I have difficulty putting into words how much I loathe technical writing that is structured anything like a textbook or dissertation.
It's a pain in the ass to use, and I wish more people would focus on concise and easily referenced/searched/indexed material in markdown rather than novels written in TeX.
For example, Agner Fog's writings are fantastic content, and awful to navigate. The Rust Programming Language does exist in book form, but I find myself referencing it constantly as a technical manual and it would suck to do that if weren't structured the way it is using mdbook.
For the love of all that is sacred, please stop writing technical manuals like I'm going to ever going to read the whole thing. Every piece of information should be short, fit entirely in a reasonably sized browser window, be indexed for search, and if it lends itself to cross-referencing it should be filled with links to itself.
That's the kind of thing that markdown and site generators using markdown excel at.
It's a pain in the ass to use, and I wish more people would focus on concise and easily referenced/searched/indexed material in markdown rather than novels written in TeX.
For example, Agner Fog's writings are fantastic content, and awful to navigate. The Rust Programming Language does exist in book form, but I find myself referencing it constantly as a technical manual and it would suck to do that if weren't structured the way it is using mdbook.
For the love of all that is sacred, please stop writing technical manuals like I'm going to ever going to read the whole thing. Every piece of information should be short, fit entirely in a reasonably sized browser window, be indexed for search, and if it lends itself to cross-referencing it should be filled with links to itself.
That's the kind of thing that markdown and site generators using markdown excel at.