4 ms·
Some docs are better than none, but writing less is not easy.
by remoquete 2y ago
Some docs are better than none, but writing less is not easy.
- namaria 2y ago"I didn't have time to write a short doc, so here's a long one"
- remoquete 2y agoMore common than you'd think...
- bayindirh 2y agoDistilling something to a short document is not easy. I write "live" docs, i.e. during the process itself, on a separate document. They become long, but they stay linear and searchable. They are very good for returning back and doing the same thing or improving the doc itself. However, if I want to distill it to a smaller doc, I'd need to spend another day to make it perfect, and I don't have time, unfortunately.
- namaria 2y agoI guess I managed to say the same as you but with less words. /s I wasn't mocking op, I was referencing Mark Twain
- bayindirh 2y agoI just wanted to extend what you said, and give a real world example to support you. I didn't think you mock the OP either. Who knows, maybe longer docs reduce misunderstanding, like how error correction reduces problems as the information moves through mediums. :)
- namaria 2y agoGot you, I was a bit on edge from previous not so fun exchanges on another thread. I go by Feynman's logic: if you can't explain it simply you don't understand it. Redundancy doesn't seem to me to be a good thing in documentation. Would make it harder to parse and maintain...
- bayindirh 2y ago> Got you, I was a bit on edge from previous not so fun exchanges on another thread. Ah, that happens, no problems on my side whatsoever. > I go by Feynman's logic: if you can't explain it simply you don't understand it. That's true, but in reality it needs a couple of passes to distill down, which needs time. An example of a live document I have written can be given as [0]. Can it be better? By miles. How much time does it need? An amount I don't have right now. "When you're poor, everything is expensive" works for time, too. So, I try to do my best when I have time, and polish it later when I have additional time for it. [0]: https://notes.bayindirh.io/notes/Hardware/Installing+a+Home+Server+on+a+Raspberry+Pi+3 https://notes.bayindirh.io/notes/Hardware/Installing+a+Home+...
- latexr 2y ago> Redundancy doesn't seem to me to be a good thing in documentation. Would make it harder to parse and maintain And increases the word count, making it less likely someone will even begin reading it.
- bayindirh 2y agoYou don't need to repetitiously write things over and over again. You can link or reference the relevant parts with clickable links. This way your document will look compact and neat while having all the necessary information contained in everywhere and every part of your documentation. Also interconnected documents reduce the burden of repeatedly updating duplicate parts. You reference or link it, and update and change it for once. Note: Yes, I have intentionally and knowingly written that way.
- latexr 2y agohttps://quoteinvestigator.com/2012/04/28/shorter-letter/ https://quoteinvestigator.com/2012/04/28/shorter-letter/ > In conclusion, Blaise Pascal wrote a version of this saying in French and it quickly moved into the English language. The notion was very popular and variants of the expression have been employed by other notable figures in history. The saying has also been assigned to some prominent individuals without adequate factual support.