I have grappled with the same conundrum.
Here are my takes on documentation writing.
First is the X axis of type of document we are called on to write.
1. There is personal writing. books included.
2. Personal Blogging and Dev Rel publishing.
3. Then there is developer tool documentation. [code snippets, sdks, libraries]
4. Then there is product documentation. [images, steps, how tos]
Then there is Y axis of tools.
1. markdown and with it Z axis of mkdocs, hugo, KMSs like obsidian <name everything markdown here>
2. rst
3. org?
3. wysiswg editors or anything custom.
I find
- markdown both ubiquitous and somewhat approachable. for most beginners.
with obsidian/logseq/... it can also work for non tech writers too.
its also more widely supported. [Github i am looking at you]
- dev rel/dev tools docs with sphinx and rst is absolutely godsend! also a vibrant ecosystem.
- product docs with mkdocs x markdown if its a consumer facing docs with lots of images and need for customizing. rst if its a developer product.
Then there is Y axis of tools. 1. markdown and with it Z axis of mkdocs, hugo, KMSs like obsidian <name everything markdown here> 2. rst 3. org? 3. wysiswg editors or anything custom.
I find - markdown both ubiquitous and somewhat approachable. for most beginners. with obsidian/logseq/... it can also work for non tech writers too. its also more widely supported. [Github i am looking at you] - dev rel/dev tools docs with sphinx and rst is absolutely godsend! also a vibrant ecosystem. - product docs with mkdocs x markdown if its a consumer facing docs with lots of images and need for customizing. rst if its a developer product.
---
I write my blog in markdown, https://blog.shaishav.kr
My team maintained https://userdocs.rapyuta.io in markdown for the last 4 years. https://github.com/rapyuta-robotics/rapyuta-io-docs
- we also maintained https://sdk.rapyuta.io/ & https://cli.rapyuta.io/ both in semiautomated rst + github actions setup