3 ms·
I don't know what the infatuation with markdown is beyond web publishing. Wysiwyg documents have been a solved problem for decades. Use what works on your platf
by fsloth 7y ago
I don't know what the infatuation with markdown is beyond web publishing. Wysiwyg documents have been a solved problem for decades. Use what works on your platform.
Markdown is fine until you realize you would like to have figures, images and tables.
I don't want to spend my time over trite details of a text based markup when I could spend it actually productively.
At that point it's way over easier to use a text processing document of choice (word or open office). I say this as a enthusiast of text based markups over decades from Latex to Markdown.
- MaxBarraclough 7y agoWysiwyg document tools aren't applicable to comments in source. You can't have images in source, but if you really need it you could add an ascii-art-style table. There are tools to generate these, such as https://ozh.github.io/ascii-tables/ https://ozh.github.io/ascii-tables/
- fsloth 7y agoThis was not about inline documentation in source, but about separate readmes. If a hand typed ascii graphic does not suffice for code comment embedded docs, then it would be better to include separate docs altogether.
- heavenlyblue 7y agoThere is a reason why everyone uses LaTeX (or similar) when it comes to professional content delivery - it actually saves you time not fighting the editor.
- fsloth 7y agoThere's no reason why internal readmes should be of 'professional quality'. It's nice, but a low barrier of entry to explain something non-trivial is more important than nice layout, IMO. "Everyone" is not using LaTeX.
- heavenlyblue 7y agoYeah. Except WYSIWYGs take way more time to do anything non-trivial. This Friday I had spent about 15 minutes trying to put an editor cursor within an empty code block in Confluence. Is that a joke? Do you know how I fixed that? I copied a non-empty block from another paragraph and then edited it. It would take me or someone else half a second to do that in Markdown/Wiki/LaTeX.
- fsloth 7y agoBy Wysiwyg I was referring to Word or OpenOffice or Google Docs or whatever the generally used word processing tool in the org is. It's totally acceptable Confluence at least tries to provide a non-programmer friendly interface for the domain experts who are not necessarily programmers. But it's not acceptable if the gui is broken...
- Izkata 7y ago> it actually saves you time not fighting the editor. And from merge conflicts.
- Spooky23 7y agoThis. Markdown is great, but I’ve seen so much time wasted on Rube Goldberg solutions that would be trivially addressed by using less cool solutions like Word or GDocs.
- quantified 7y agoIf the corporate ownership changes, the markdown files will stay. GDocs or Atlassian subscriptions might be ended without migrating the data, leading to loss of key info. Yes it happens!
- AmericanChopper 7y agoFor certain use cases, markdown is arguably the best solution. For a team that uses an SCM like github (or any of the ones that natively render markdown), and that also has simple documentation needs, I can’t imagine a better solution. Markdown is fast to create, can be read rendered or not, can be included in your project repo and in pull requests. Images are easy in markdown, simple tables are easy in markdown (complicated tables very quickly move into don’t bother territory though). It uses the tools and workflow you already have to solve a problem very well. If you need something more complicated than markdown can provide (depending on your renderer, that could something as trivial as line breaks inside the cells of a table), then it’s obviously not going work. But for any solution that’s great in one use case, there’ll be others where it’s completely impractical.