27 ms·
Rst is technically vastly superior to MD. Yet I predict that MD will prevail. VHS style. I hugely prefer to write in RST, but as soon as I'm not alone we alway
by thesnide 2y ago
Rst is technically vastly superior to MD. Yet I predict that MD will prevail. VHS style.
I hugely prefer to write in RST, but as soon as I'm not alone we always switch to MD, given enough coworkers.
- 12_throw_away 2y agoYep, it seems like the platonic ideal of a "worse is better" situation. I do think this is, ironically, partly a documentation problem - when I last tried to create docs for a python codebase (several years ago), I found the rST docs to be sorely lacking in basic, introductory "here are the core mental models for how this works" sorts of content. Maybe the situation is better now? (Or maybe I just missed them, but not for lack of trying) But I feel like then, it's obvious README.md prevailed and will continue to be the standard - you can use markdown for a very long time without ever reading any documentation at all. Worse is better, I guess.
- bloopernova 2y agoIn my opinion, I don't think it's "worse", just simpler. Plus it's more ubiquitous, supported by Github etc etc. Although Github may not be the best yardstick there, because they render documents written in Emacs' org-mode too! (which I very much appreciate, I prefer writing in org to writing in Markdown) I'm hoping that LLMs will make it more streamlined when documenting existing code. Not so much as a replacement for text written by experts, but in converting code into diagrams. LLMs or similar "understand" a codebase by tokenizing it (as is my understanding), so turning that into a nice documentation skeleton should be possible.