4 ms·
Wysiwyg 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 tab
by MaxBarraclough 7y ago
Wysiwyg 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.