3 ms·
> deep linking into a different document This is difficult in every docu system.
by euroderf 3y ago
> deep linking into a different document
This is difficult in every docu system.
- LegibleCrimson 3y agoNot hard with RST/Sphinx, but that comes with other usability nits.
- boxed 3y agoIt's fairly easy in rST. I just can never remember the syntax :P We switched the iommi docs from markdown to rST for this and many other similar issues of rST being more powerful.
- riskable 3y agoReStructuredText (.rst, what Sphinx uses) handles it quite well. I understand why Markdown became so popular (super easy/intuitive) but what I don't understand is why so many documentation systems use it. It's quite limited... On purpose! You want to support simple text features in a forum or comments on a website? Markdown is perfect. You want to support basically every documentation feature imaginable while still retaining reasonable ease-of-use? ReStructuredText is the way to go.
- euroderf 3y agoAs I understand it, rST and Asciidoc are roughly equivalent in that they provide significant document-oriented upgrades to Markdown - upgrades that are on the order of Docbook. This makes them attractive. But you won't convince me that cross-document deep linking is a solved problem unless you accept that the use case is a static document base. Anything to do with products under continuing development is going to bring headaches. Is there any CMS that "solves" this in a robust way ? I wonder.
- ninacomputer 3y agonah we use asciidoc for this. worked next to the guy who invented it back in the day. another team at our company used to to make topic-based authoring the CMS standard. been doing this fine for years now and even the writers seem happy (super rare for tech writers innit)