Markdown type documents in a vcs are the best documentation system in my opinion. The problem really shows up when you are then trying to get non-technical users to participate, hence the abomination of wysiwyg web editors such as confluences (which is indeed broken, especially without plugins).
Markdown has lots of variants but is ok to wrangle most of time and pandoc handles it very well. Github renders it natively.
Emacs org mode is awesome and github renders it native but when not everyone is using emacs or a tool with org-mode plugins it it can cause issues when others try to access/edit it when using some of the more advanced features, so I use it for personal use and as a data science notebook. It replaces Jupyter notebook for me.
Asciidoc and Asciidoctor are currently the particular implimentation of markdown that is working towards a defined spec (https://asciidoctor.org/news/2019/01/07/asciidoc-spec-propos...) that I am leaning into the most. They are the best of both worlds. I am planning on moving my websites to asciidoc instead of org mode.
Documentation from code and code comments is much more specific and so I would say outside discussion scope.
I think that a markdown with a more well thought out spec such as asciidoc(tor) are working towards is going to be the future, and I think that the wysiwyg tools themselves are the main pain point and are what need to be worked on the most.
In the past when I have had to deal with confluence I have just asked confluence admins if we can use the github or html frames plugins so I can do documentation independent of confluence itself.
edit of a new page/section is a PR to the repo.
once merged, you can auto deploy it to the target destination, rendering via jekyll or mkdocs or other things.
Discussions happen in PRs in that model. (you can also added previews of the PRs and deploy these next to the production version of the site)
Markdown has lots of variants but is ok to wrangle most of time and pandoc handles it very well. Github renders it natively.
Emacs org mode is awesome and github renders it native but when not everyone is using emacs or a tool with org-mode plugins it it can cause issues when others try to access/edit it when using some of the more advanced features, so I use it for personal use and as a data science notebook. It replaces Jupyter notebook for me.
Asciidoc and Asciidoctor are currently the particular implimentation of markdown that is working towards a defined spec (https://asciidoctor.org/news/2019/01/07/asciidoc-spec-propos...) that I am leaning into the most. They are the best of both worlds. I am planning on moving my websites to asciidoc instead of org mode.
Documentation from code and code comments is much more specific and so I would say outside discussion scope.
I think that a markdown with a more well thought out spec such as asciidoc(tor) are working towards is going to be the future, and I think that the wysiwyg tools themselves are the main pain point and are what need to be worked on the most.
In the past when I have had to deal with confluence I have just asked confluence admins if we can use the github or html frames plugins so I can do documentation independent of confluence itself.