4 ms·
This 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, t
by fsloth 7y ago
This 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.