4 ms·
I believe asciidoc would be a better fit for it, especially because there are already tools/plugins for java for generating documentation, so the wheel must no
by madduci 4y ago
I believe asciidoc would be a better fit for it, especially because there are already tools/plugins for java for generating documentation, so the wheel must not be (once again) reinvented
- exabrial 4y agoI think AsciiDoc is a good choice, but it does suffer from the single author ecosystem problem (effectively one maintainer). If the ecosystem were to jump to MarkDown, I have a feeling they'd just make the doc system pluggable eventually and we could sub in AsciiDoc in the future.
- glmdev 4y agoI also think "adoptability" should be a consideration. Perhaps AsciiDoc would be a slightly better fit, but every developer I know is already familiar with MarkDown and at the end of the day convincing people to write good docblocks is easier if they don't have to pick up new syntax.
- eadler 4y agoI can't stand both writing and reading markdown and find its use painful. While HTML isn't the nicest at least it has (a) separate markup and content and (b) predictable output.
- avgcorrection 4y agoDoesn’t AsciiDoc have a problem with nesting elements?