3 ms·

My grandmother can create better docs than most programmers, but not because she's some technical wizard. She uses MS Word. Imagine, a program designed to allow

My grandmother can create better docs than most programmers, but not because she's some technical wizard. She uses MS Word. Imagine, a program designed to allow humans to lay out and format a document quickly and easily... programmers prefer to hack up ascii art and forego the graphical layout and formatting tools developed 30 years ago. And then they complain that docs are hard to read/write...

kstrauser 2y ago
Grandma’s doc may not be readable in 30 years. I can look at basically every text file written since ASCII came along with standard tools. Also, since Grandma isn’t a programmer, she’s probably not collaborating on her doc with a bunch of distant people using a version control system with patch requests. Shiny tools are nice when it’s only you and you don’t need to keep the results forever.
- 0xbadcafebee 2y ago
  Lol, dude, Word files have been readable by open source tools since forever. MS Word itself supports many different formats including OpenDocument, so there is absolutely no problem with being able to read them in 30 years. MS Word supports version control, but patches are a terrible idea for documents. Again, the whole point of a document is to make it easy to read, so the formatting becomes a huge pain in the ass for a patch. Patches are designed for lines of code, not the formatting, layout and content of rich text documents. Trying to force documentation to work like code is making the computer happy, rather than the computer making people happy. It's the opposite of what technology is supposed to be for. Think about what you're spending your life on. You gonna look back when you're 80 and think, gosh, I'm so glad I spent those extra hours going back and forth with a dozen people on the internet to try to approve an update to documentation? I'm so glad I spent an extra hour tweaking this program code so that this document would have an embedded table aligned right? I'm so glad I had to write a separate program to be able to format this Markdown Table so that I could actually edit and save it so that it renders? Docs should be living / not require requests for patching. Humans should be entrusted to just update a document immediately, with a log and comments to allow reverting entries only if necessary. Aka a wiki (and a WYSIWYG one at that). The whole purpose of patch requests is not to gatekeep information, it's to make sure a change doesn't blow up a program. Documentation isn't a program, just change the document.
Kwpolska 2y ago
Word sucks if you want consistent formatting. It has styles, but they randomly glitch out and can't always handle everything. I want docs in HTML, not PDF, and definitely not DOCX. The issues some programmers have are issues with content, not formatting.

kstrauser 2y ago

Grandma’s doc may not be readable in 30 years. I can look at basically every text file written since ASCII came along with standard tools. Also, since Grandma isn’t a programmer, she’s probably not collaborating on her doc with a bunch of distant people using a version control system with patch requests. Shiny tools are nice when it’s only you and you don’t need to keep the results forever.

0xbadcafebee 2y ago
Lol, dude, Word files have been readable by open source tools since forever. MS Word itself supports many different formats including OpenDocument, so there is absolutely no problem with being able to read them in 30 years. MS Word supports version control, but patches are a terrible idea for documents. Again, the whole point of a document is to make it easy to read, so the formatting becomes a huge pain in the ass for a patch. Patches are designed for lines of code, not the formatting, layout and content of rich text documents. Trying to force documentation to work like code is making the computer happy, rather than the computer making people happy. It's the opposite of what technology is supposed to be for. Think about what you're spending your life on. You gonna look back when you're 80 and think, gosh, I'm so glad I spent those extra hours going back and forth with a dozen people on the internet to try to approve an update to documentation? I'm so glad I spent an extra hour tweaking this program code so that this document would have an embedded table aligned right? I'm so glad I had to write a separate program to be able to format this Markdown Table so that I could actually edit and save it so that it renders? Docs should be living / not require requests for patching. Humans should be entrusted to just update a document immediately, with a log and comments to allow reverting entries only if necessary. Aka a wiki (and a WYSIWYG one at that). The whole purpose of patch requests is not to gatekeep information, it's to make sure a change doesn't blow up a program. Documentation isn't a program, just change the document.

Kwpolska 2y ago

Word sucks if you want consistent formatting. It has styles, but they randomly glitch out and can't always handle everything. I want docs in HTML, not PDF, and definitely not DOCX. The issues some programmers have are issues with content, not formatting.