Re: Concrete suggestions to improve Org mode third-party integration :: an afterthought following Karl Voit's Orgdown proposal

[Juan Manuel Macías]

Ihor Radchenko writes:

> Ok. Let me explain my thought process.
>
> First of all, there is no burden on users of Org mode in making edits to
> orgmode.org. It is a burden on Org contributors.
>
> One of the aims of my proposal is reducing this burden by involving
> non-emacs users to provide contributions to Org (e.g. by making more
> tests for Org-element parser). To do it, we need to make the
> contribution process for non-emacs developers easier. Ideally, without
> too much effort on our side.
>
> The idea of involving non-emacs users does have a potential because we
> do know that third-party tools are already using Org. The problem is the
> disconnect between those tools and Org mode proper.
>
> The sources of the disconnect are (1) lack of technical "blueprints" for
> Org that do not require knowing Elisp; (2) lack of discovereability of
> Org mode as something that can live outside narrow field of Emacs. In
> this branch of our discussion, I am going to talk about the second
> point.
>
> People simply do not expect to see a markup language when they encounter
> a link with "Org mode for Emacs" title. Someone looking for Org mode
> markup to be used in, say, websites will think that "Org mode for Emacs"
> is limited to Emacs. Someone just interested in plain text markup will
> find no relevance at all.
>
> Title is important. If we care at all about orgmode.org website
> appearing in search results, we want the title and the summary to have 2
> main properties: (1) Provide search keywords to make it searchable by
> potentially interested people; (2) Provide a title that immediately
> signal that our website contains the information people are looking for.
>
> Now, we need to understand what kind of people may be looking to
> orgmode.org website.
>
> 1. Existing emacs users
>
>    If a Emacs user is faced with "Org mode for Emacs", the word "Emacs"
>    is indeed recognisable. On the other hand, the word "Org mode" does
>    not provide much further info, except that it is a major (or maybe
>    minor?) mode for "Org"??
>    
>    Now, consider "Org mode: your life in plain text".
>    For emacs users, "Org mode" is not just a strange phrase, but a very
>    clear indication that we are talking about Emacs.
>    The "your life in plain text" provides extra information about what
>    "Org mode" refers to. Clearly, text documents and "your life in plain
>    text" should resonate with every Emacs user's soul.
>
>    We can change the second variant of the title to contain "Emacs", but
>    will it add much value? I am not convinced. On the other hand, making
>    title too long or too complex _is_ bad. Long titles tend to be
>    skipped (there was even formal research on this!)
>
> 2. Non-emacs users interested in plain text markup
>
>    These users know nothing about Emacs and "Org mode" has no meaning
>    for them as is. So, we do need something more descriptive.
>    Adding "Emacs" may be fine, but it will serve no purpose for people
>    not familiar with emacs. Just another unknown term making the title
>    longer.
>
> 3. Non-emacs users interested in GTD/project management, etc
>    "Org mode: your life in plain text" is somewhat relevant when people
>    are looking to manage "life" (typically true for GTD enthusiasts).
>
>    Though we can probably do better for this category.
>    Maybe "Org mode: manage your life and notes in plain text"?
>    Though it makes the title less relevant to group #2.
>
> 4. Researchers looking for ipython-like environment
>
>    Not covered, except by reading my proposed site summary. I am not
>    sure how we can improve title for this audience.
>
> 5. ??? (Suggestions are welcome)
>
> Of course, better suggestions for the title are welcome. I just wanted
> to make it clear the reasoning I do not like the current title and how
> the proposed alternative is better (though not ideal).
>
> Finally, I want to emphasise that our aim for search engines is not
> advertising Emacs (we already do it by trapping users inside Org and
> making them switch to Emacs by force :evil_laughter:). The aim is
> encouraging people to use and contribute to Org mode in useful ways
> (even unrelated to writing Elisp or, really, any code at all).
>
> Search result is just an entrance for users to be curious about the new
> beast of "Org mode". The website front page is the means to make users
> try. And the Org mode itself is the way to make users fall in love with
> Org in one way or another (even unrelated to Emacs [at least
> initially]).

Ihor, thank you very much for explaining your motivation in detail. I
think I understand it and (on the important points) I share it. In my
case, as an Org Mode user I often feel a mixture of happiness and
frustration. Happiness on using Org. Frustration every time I want to
recommend Org to many of my friends and colleagues, who don't even use
Emacs. GNU Emacs is a great, labyrinthine, fascinating building. Almost
like a city. And Org is a room on one of the upper floors. In the
Org-room (including Org-Roam! :-) there is a lot of fun, great people,
great music. But whoever wants to get there must go through a series of
levels, intricate corridors that are like a kind of learning path. Emacs
is great, but you can't learn to use it in two days. It takes time to
adapt it to your needs, get to know it, even love it. Sorry to be so
metaphorical and poetic, but it is the only way I can find to explain
what is, in many ways, a personal learning process (even the init Emacs
file could be understood as a kind of autobiography...). I wish the entry
into Org was smoother and more direct, but being an Emacs mode, it is
necessary to go through Emacs. And this gets more crude for
non-technical, Humanities users, who I think could be very happy using
Org and not Word or other modern auto-torture methods :-)

I came to Org been an Emacs user already, so I was reasonably familiar
with Emacs and Elisp, although what I used most was AUCTeX (and Markdown
for my docs). I heard about Org but it never caught my attention, until
one day I read the Org compact guide and I was fascinated that such a
thing existed (and it was just the compact guide!).

TL; DR: I understand and share the maneuver of baiting new and potential
users. But I see it difficult. Users who have never used Emacs will have
to go through the Emacs learning process first, especially non-technical
users or those who come from the country of word processors, that is,
Mordor. On the other hand, Org as a lightweight markup language is only
a tiny part of Org. I don't think Org is better or worse as a markup
language than Markdown, asciidoc or other similar formats. I think the
important thing about Org here is the integration of a series of
resources: a whole that is more important than the sum of the parts
(https://en.wikipedia.org/wiki/Emergentism).

Best regards,

Juan Manuel