4 ms·
That argument doesn't work both ways. One group has far more stringent requirements than the other as evidenced by your use of the word "acceptable". Web docum
by alexvoda 5y ago
That argument doesn't work both ways. One group has far more stringent requirements than the other as evidenced by your use of the word "acceptable".
Web documentation is easy to produce and is acceptable to many. All other kinds of documentation can also be converted into web documentation, therefore you do not have to spend extra effort for it.
Terminal documentation is more difficult due to the limitations of displaying things in the terminal, therefore it requires more effort.
- arghwhat 5y agoI’m sorry, what? I certainly agree that those who prefer terminals are a subset of developers - despite this missing the point of terminal-friendly documentation also means generally reusable and integration friendly, unlike a full web application - but terminal documentation is objectively orders of magnitude less work than writing web app for showing documentation. Terminal documentation just means plan text. You print it, that’s it. Making it pretty involves indents and line wrapping. Any source formatting is just ignored.
- throwamon 5y agoWho said it has to be a "full web application"? Where are the orders of magnitude more work in parsing text and saving it as HTML files?
- arghwhat 5y agorustdoc, the tool being discussed, generates a full, interactive web application as documentation. Plus, while one can dump plain text to HTML files it's still easier to just print the text.
- staticassertion 5y agoIf it were orders of magnitude less work to get the same results in a terminal that you get in a browser we wouldn't have browsers.
- arghwhat 5y agoI'd love to know how you arrived at that conclusion, as it seems extremely illogical. Text based interfaces and terminal applications came first exactly because they are simpler than web browsers and applications. We're not talking about a "TUI" app here - a terminal doc tool just dumps plaintext and terminates.