AsciiDoc

Raised as a usability problem by 12 people on Hacker News over 13 years (2013–2025), in 8 threads.

People raised many different problems with AsciiDoc, but no single problem has yet been raised by 3 people in 3 different months and threads.

Unreviewed issues were grouped by machine: Claude Haiku labelled each comment as a usability complaint, named what it's about and summed up the problem in a line, and a small model grouped similar problems. Nobody has checked them by hand. Expect mistakes.

The newest 12 complaints

Steeper learning curve than Markdown for newcomers2025-11-10
Has to look up reference and link syntax every time after years of use2025-02-06
Syntax is cumbersome and tooling is often subpar or unusable2025-02-06
Tooling is sparse, and doing anything with it is a pain2025-02-06
Table syntax is unreadable as a table and hard to write2023-02-07
Trailing + line breaks get mixed with ordinary plus signs and break when re-wrapping paragraphs2023-02-07
Documentation is bare, hard to find examples, poorly explained2023-02-06
Varying delimiter line length when nesting blocks is arcane and error-prone2022-09-16
Too many steps for quick note-taking with tables, links, and images2022-06-17
30-second build times make tweaking the book painfully slow2021-12-06
Complex table markup doesn't visually resemble the rendered table, and errors are hard to spot2020-03-24
Built on the DocBook XML toolchain, making it an absolute bear to use2013-04-26