Great points about links, especially external links — it makes a lot more sense in the context of a documentation site where you might have the same external link referenced multiple times in the site, but you only want to have to update it once if it changes.
The real gamechanger is for internal links (rST+Sphinx) and the use of the `:ref:` and `:doc:` directives so that you can reference an anchor or a doc link in the same content without having to type the header manually (which will inevitably go stale).
> do we have a language server that can look up available references, headlines, figure names etc and help you auto complete?
That would be a total gamechanger! Having the ability to do ref/doc links and not have to worry about stale topic headers is another thing I loved about writing in rST that I miss now that I'm back in markdown.
Markdown has a great linter in markdownlint. When I worked in rST, I found the syntax to be super extensible, and tables much easier to write (list tables! amazing!) but without an effective linter, writing in rST was consistently painful.
Whitespace has meaning, so I had to set up all sorts of indent highlights and dots for each space in my IDE to try to avoid screwing up the syntax inadvertently.
rst-lint and others exist, but don't seem to be maintained, and didn't seem to have documentation about how to add support for custom directives (which are definitely one of the key advantages of rST).
I'd write in rST again, but without an effective linter to stop me from making easy mistakes, I wouldn't be happy about it.
Thanks for reading! The source is my experience working in the industry and interacting with other technical writers and customer feedback submitted on doc pages, posted in Slack communities, and more. I've spent years reading comments from readers asking for updated documentation because it has a screenshot of a different UI than the one they use—even though the rest of the content is accurate.
It's difficult to find published research about technical documentation because basically only Nielsen Norman Group is doing extensive research on web content. Baymard Institute, who I link to in the post, also does quite a bit of research but even more broadly and mostly on overall website and web marketing content.
The real gamechanger is for internal links (rST+Sphinx) and the use of the `:ref:` and `:doc:` directives so that you can reference an anchor or a doc link in the same content without having to type the header manually (which will inevitably go stale).
https://www.sphinx-doc.org/en/master/usage/referencing.html#...
that is one of the things I miss most about writing in rST, for sure.