Comment by philipwhiuk | Hacker News Reader

Comment by philipwhiuk | Hacker News Reader

> If you're writing a quick README or a short-lived doc, Markdown is fine. It's fast, approachable, and does the job. If you're building a developer documentation site that needs some structure, reStructuredText or AsciiDoc are better choices.

This is dumb. If I'm writing developer documentation I'm not writing it for a machine. And if the aim here is to expose it to a LLM, then the LLM needs to get smarter about semantics, not force us back to formats that are more technically complex to write and maintain in order to re-create 'the semantic web' - a flawed concept that has failed to catch on.

If the LLM needs context on content that humans don't need, the LLM needs fixing, not the content.

> With Markdown as your source, you can't easily go to another format.

File->Print->PDF.

Was that hard? (I admit it's still bizarre that Chrome puts 'Save As PDF' under Print).

(Apparently you can also go via LaTeX if you love a CLI)

> If I'm writing developer documentation I'm not writing it for a machine. And if the aim here is to expose it to a LLM, then the LLM needs to get smarter about semantics, not force us back to formats that are more technically complex to write and maintain

AsciiDoc is much better than Markdown for docs intended for humans that are more than short, README type of documents. Any advantage it has for documents intended for LLMs is a side effect of that.

Many consider AsciiDoc being too complex.

The history of tech is full of "X is better than Y. We should use X", only for X to die. It doesn't matter what is better; it matters what is used. For better or worse, Markdown is what is used.

This is the kind of dismissive sneer the HN guidelines advise against.

You can write dev docs for humans and still want machine readability (without caring about whether some LLM can make sense of the docs).

Machine readability is how you repurpose your own documentation in different contexts. If your documentation it isn't machine readable it might as well be in a .doc(x) file.

Reply on news.ycombinator.com