Everyone can contribute to the documentation to make it better. Consider doing so.

Remember, no one gets paid to maintain or document Emacs, so the quality of the documentation is really pretty remarkable for how good it is.

It can always be made better, though.

What makes learning Emacs and Elisp so hard? I think you’ve begged the question in the classic sense—your question contains the answer! The issue I think is that to really understand Emacs you have to understand Elisp and the Emacs environment.

If you focus only on one, it’s hard to work with Emacs. Knowing Elisp without understanding how to work with hooks, and modes, and when (and whether) to work with the Custom system, and when configuration code should load before vs. after a package loads… well, you’re not going to be able to do a whole lot with that Elisp! And Emacs knowledge without Elisp means you’re going to know what you want to do and maybe even how to do it but you’re going to have some fundamental misunderstandings of the code itself, leading to errors and bugs and a lot of frustration.

Thinking about this, I think the reason the documentation can be so challenging to figure out is that, as someone said further up there, this is all run by volunteer efforts, and, as such, they have to prioritize where their limited resources go. So the approach it seems to me that they’ve taken is to document as much of the Emacs environment as they can, but focus not on all of Elisp, but how it’s different from other Lisps, and assume you can teach yourself Lisp.

I’m not really sure it’s true that this was the purposeful prioritization from the documentation writers—there’s a pretty extensive Elisp manual, and a nice Elisp tutorial in the manual (typically C-h i)—but it’s not the level of resources nor the beginner-friendly approach that you see with learning a (somewhat) more practical Lisp, like Scheme or Racket or Common Lisp or Clojure. I don’t mean to put words in the mouth of the tireless and selfless documentation writers, nor at all demean them! But either way, it’s the same result from a learner’s perspective.

So given the situation (as I see it), how do you learn Emacs? I highly recommend learning another Lisp, since there are more resources and tutorials on those than Elisp. Racket and Scheme.are IMO the easiest to get started with, and fun besides.

One final thought on learning Emacs: I think I stunted my growth for a while by using a framework on top of Emacs—I learned neither proper Elisp nor how Emacs worked. I learned a little about how my framework worked, and little about Emacs itself. I used Doom Emacs, but most frameworks have this issue. I’ve heard there are some frameworks that are better geared towards teaching you Emacs, so maybe this doesn’t apply at all. But I think Doom Emacs is more geared to transitioning folks from Vim (which helped me, for sure!), and the framework they’ve built on top of it, while powerful, isn’t, in my “n of 1” experience, good for learning.

Anyway, hope these thoughts help, and besides agreeing with folks that one of the best things you can do to learn and help others learn is to contribute to the documentation, this and the org-mode reddit are good places to ask clarifications—especially if it’s clear it’s a clarification and you’ve attempted your research first! (We’re friendly, but we’re friendlier if you demonstrate you’re putting in the effort too.)

Cheers!

If I understand correctly, you are asking why is documentation using bad code examples that are not explanatory and/or usable?

If so, then I believe we can exonerate the emacs community from this issue as this is an industry-wide problem. I recall trying to figure out what a .NET class do from the generic unusable examples given in MS code, and more recently trying to divine meaning from the almost usable but never truly so code examples in Angular documentation. And you’ll see that everywhere. I got used to ignore documentation and just read the code. Tests sometimes help as they are actual programs that use the stuff in question, but it does seem like writing good, usable documentation is an art form no one bothered to master. Or even apprentice in.

There’s a reason to that, code examples are written by people who are experts in the technology they are documenting. They have no way of knowing what is needed for someone new to understand in order to use it, so they default on writing the most basic code example they can come up with. It’s a known issue and you eventually learn to live with it.

Also, don’t bother complaining. You are getting this great tool (either emacs or Org-Mode) free and due to the great effort of its writers and maintainers (and I am always amazed at the scope of things that were created this way, it’s truly something to be proud of), so be thankful that it actually has documentation and besides, if you don’t like something, fix it and send them the patch, don’t complain! I mean, you won’t get to write that patch because you can’t understand the program due to its documentation, but hey, who said life is fair.