Org-mode is a beast. A fantastic beast, much like Emacs itself. You dive in, but there's always more to learn. Some things may be for you and some things don't. Everyone should give it a try.
A little known fact, even among most org-users: Github can render org-mode files to HTML directly if checked into a repo, thus you can write your README files as org-files.
This alone was enough to make me drop Markdown as my go-to format for semi-formatted text-files.
A subtle killer feature here is org-babel. You can embed proper code in your text-files and have your editor (at least Emacs) understand them as such. Which makes it excellent for writing technical documentation for projects where code is involved.
A little known fact, even among most org-users: Github can render org-mode files to HTML directly if checked into a repo, thus you can write your README files as org-files.
Shameless example: https://github.com/josteink/csharp-mode/blob/master/README.o...
This alone was enough to make me drop Markdown as my go-to format for semi-formatted text-files.
A subtle killer feature here is org-babel. You can embed proper code in your text-files and have your editor (at least Emacs) understand them as such. Which makes it excellent for writing technical documentation for projects where code is involved.