5 ms·

As a developer that really likes to document stuff I don't like markdown. It's limited and as the article states too fragmented. I started using AsciiDoc a whil

As a developer that really likes to document stuff I don't like markdown. It's limited and as the article states too fragmented. I started using AsciiDoc a while back. It's like markdown but with more advanced options for true documentation stuff like charts, tables (formatted!), diagrams and more.

wakeupcall 5y ago
I share the same opinion. Its limit make it useful only for a very small set of use cases. It's being used a lot for code documentation, but MD is bad fit for documentation. Good documentation requires a lot more formatting and cross-referencing than you'd think. Every language I'm using that has been using MD (for embedded and online docs) added extensions, resulting in more fragmentation. So in general I switch between 3-4 differently-flavoured markdowns constantly. The extended syntax used by various projects sucks. Where did the simplicity of MD go? It reads poorly when unformatted, which is how I read it 99.9% of the time. I gravitate more towards RST as it's a bit more widely used, but also agree about AsciiDoc.
- fjorde 5y ago
  I agree with both these points. Inter-document references are bad in markdown and wiki style formats. Wikipedia is replete with overlapping and contradictory information that should be pulled from a single source. Do you have any ideas re link-rot, or underlying assets changing and semantic links becoming invalid? How do you reference a code asset whose name could change, what will not only replace all references in the code but also in the documentation?
  - wakeupcall 5y ago
    Cross-reference checking is a huge problem on it's own, almost unrelated to the formatting being used. Some language tooling do provide cross-ref checking, generally as an extra step part of the documentation generation process. I don't have anything to add to the table compared to what we do already...
throwaway_Aef8 5y ago
For the "more advanced options for true documentation stuff like charts, tables (formatted!), diagrams and more." you might like Obisidian. But that steers you back towards markdown. How deeply do you not like markdown?
- goldsteinq 5y ago
  I like Markdown, but I don’t like proprietary Electron apps.

wakeupcall 5y ago

I share the same opinion. Its limit make it useful only for a very small set of use cases. It's being used a lot for code documentation, but MD is bad fit for documentation. Good documentation requires a lot more formatting and cross-referencing than you'd think. Every language I'm using that has been using MD (for embedded and online docs) added extensions, resulting in more fragmentation. So in general I switch between 3-4 differently-flavoured markdowns constantly. The extended syntax used by various projects sucks. Where did the simplicity of MD go? It reads poorly when unformatted, which is how I read it 99.9% of the time. I gravitate more towards RST as it's a bit more widely used, but also agree about AsciiDoc.

fjorde 5y ago
I agree with both these points. Inter-document references are bad in markdown and wiki style formats. Wikipedia is replete with overlapping and contradictory information that should be pulled from a single source. Do you have any ideas re link-rot, or underlying assets changing and semantic links becoming invalid? How do you reference a code asset whose name could change, what will not only replace all references in the code but also in the documentation?
- wakeupcall 5y ago
  Cross-reference checking is a huge problem on it's own, almost unrelated to the formatting being used. Some language tooling do provide cross-ref checking, generally as an extra step part of the documentation generation process. I don't have anything to add to the table compared to what we do already...

throwaway_Aef8 5y ago

For the "more advanced options for true documentation stuff like charts, tables (formatted!), diagrams and more." you might like Obisidian. But that steers you back towards markdown. How deeply do you not like markdown?

goldsteinq 5y ago
I like Markdown, but I don’t like proprietary Electron apps.