Also, I prefer not leaving empty blank lines in between. Factors like that can change one's perception of readability.
- free data (not locked by proprietary systems like Word) - ability to diff, search easily - ability to quickly refactor (biggest one for me) of not just content but markup too!
Now readability is subjective plus if you know what you are reading.
If you know Org markup, reading even raw Org will be easy. If you know Markdown, reading Markdown will be easy. If you don't know Org, you might think that the headings look like bullets. But that just because you don't know it not because if is less 'readable'.
I linked the raw Org earlier. Here is the Markdown conversion of the the same Org source: https://gitlab.com/kaushalmodi/kaushalmodi.gitlab.io/raw/mas...
To a Markdown-untrained eye, that wouldn't look too "readable".
Now of course, if you use a good editor that allows folding of headings, optional hiding of markup, coloring code blocks in the right syntax, etc, that definitely becomes more readable than raw. The same applies to Markdown.
It's basically -- Pick the right tool to make the experience more pleasant. But even if you use a wrong tool, plaintext content will allow you to get the job done. It's your choosing.
So as I mentioned earlier, "readability" is a perception, subjective to each individual. Based on their experience with plaintext, Org or Markdown "readability" can change. But the plusses of plaintext I mentioned in the very beginning stay unaffected by that.
Also, your markup without the blank lines and the fact that headings look like bullets to me make it harder to follow.
That's because I like that and only I am using that.
If it's a matter of team collaboration, certain ground rules can be set to resolve that.. like use blank lines after headings. You might be surprised but there's actually an Org mode setting in Emacs which can be configured to set how many blank lines to auto-insert after each heading -- I set that to zero.
> the fact that headings look like bullets to me make it harder to follow.
If you start using Org, it won't look like that. In fact, I use hyphens for list items in Markdown too as they work there too, so there is not too much context switching as I switch between Org and Markdown. I went through a lot of that as I was developing the ox-hugo package :)
Also in Org, lines starting with "# " are comments, which intuitively are comments in many languages. Markdown doesn't have comment syntax! I need to do stuff like below to fake a comment in Markdown:
[//]: # "comment"
But if you do use emacs and org, there's absolutely no question that org is more readable than markdown. It's a bit like comparing Word to plaintext, they are just not the same tool.
EDIT: I guess the article could be interpreted as convincing you to switch to org so that's probably what you mean, but I sort of read it as "if you use emacs, org is better than markdown", which I can't really argue with. But if emacs is a non-starter for some people, I find pandoc is very useful for moving documents back and forth.
Sure it does, <!-- ... -->. This is also what Emacs will automatically use if you add-file-local-variable in a Markdown file, so I don't know why you're using that weird format.
There's a stronger argument to made that org-mode doesn't really have comments. As far as I can tell syntax-ppss never gives me non-nil for them. Sure, a line like "# foo" appears in a comment face, but so does a line like "#+ASDF:" or "#+BEGIN_SRC" (but not a line like "#+TITLE:"). So whether something is a "comment" depends on its contents, which means it's syntax, never really a comment.
I was thinking of native comment syntax in Markdown, which is absent. But you are right, HTML comments, like anything else HTML work fine in Markdown. So you have a valid point.
> There's a stronger argument to made that org-mode doesn't really have comments. As far as I can tell syntax-ppss never gives me non-nil for them.
Hmm, I had never checked that. That's good to know. M-x comment-dwim works though. This might be good to report as Emacs bug.
> Sure, a line like "# foo" appears in a comment face,
That's a proper comment as per Org spec. Those lines are completely ignored by Org, for any parsing or for any exporting business.
> but so does a line like "#+ASDF:" or "#+BEGIN_SRC" (but not a line like "#+TITLE:").
Because those are not comments. It's not an official term but I think of those as pseudo-comments. The "#+.." lines while looking like comments have a special meaning to Org. The meaning of those can also be exporter backend dependent.
> So whether something is a "comment" depends on its contents, which means it's syntax, never really a comment.
Yes only for #+ comments.
This is because org overrides massive amounts of Emacs default functions - in this case, in org-setup-comments-handling. org-mode doesn't really use syntax tables normally. Similar problems occur with strings. They are known issues, and unlikely to be fixed.
[1]: http://orgmode.org/worg/dev/org-syntax.html#Affiliated_keywo...
But think again, if it's a good plaintext markup language, why would we concern about an editor anyway?
TBH the time it's being useful is when I am writing in _any_ plaintext editor. Not a great example but if I'm already used to pressing Ctrl + B for the past twenty years, why would Shift + _ suddenly make things better?
I work with a colleague who edits Org mode files in Vim just fine. But if you use Emacs to edit the same file, you get the benefits of subtree folding, syntax highlighting, etc.
You can get the same in Vim too, but someone has to develop a plugin for that.
So talking about my colleague editing Org mode in Vim, once he is done editing, he runs a Makefile that runs emacs in batch mode to run the Org exporter.
> TBH the time it's being useful is when I am writing in _any_ plaintext editor.
You still can, as I mentioned above.
The benefit of plain text is that it can be easily edited in any editor. Now emacs just adds features related to viewing (folding, syntax highlighting) and navigating on top of that. Given time and enough interest, any editor can support those features for Org mode files.