It provides multiple layers of documentation along multiple dimensions.
Say you're an end-user. Where do you start? Maybe you read the tour on the webpage. Maybe you watch one of the countless videos. The first time you open Emacs, your cursor is on a link to the tutorial. The tutorial is interactive and allows you to save and continue later. The system sets you up for success in learning.
The tutorial leads you to the manual, written in Texinfo which is published in multiple formats. Within Emacs, you can use the info browser (you can access the same from the terminal outside of Emacs) to search and navigate the documentation. All manuals and references are also published to Html (as single page to facilitate searching terms across sections), as well as PDF and bound paper copies (available from the FSF). There is no single interface to the documentation. The interface can be a web browser, the info browser, your thumb on a physical page, etc.
Info/texinfo is amazing. Documentation is indexed. This allows you to search for terms, as well as section headers and keywords. If a term doesn't appear explicitly within the text or within your current document, it may be included as an index. What would fail in the pdf or html is found this way. You can search across documents (for example, the user manual vs. the programming reference). The apropos function even compiles search results as a table of contents.
Navigation of the documentation is robust. Forward, backward, up, down, top. Within Emacs, this is even better. There are lookups for functions, variables, and symbols. Lookups within the various documents (manual, reference, do strings, etc) is quick and integrated. Because the cost/pain of lookup is low, as well as terms indexed, separate documents feel like one.
Each function and variable has a quick-to-access docstring. The docstring may include links to other useful features or reference to other documentation. Documentation always has a link to the source code.
A lot of what I've said addresses the interface to the documentation. It's also important to consider the use-cases for the documentation and its intended audience. There are tutorials to introduce high level concepts (assuming zero prior knowledge), there are references for in-depth explanation of component details, there are docstrings to explain specific functionality, and there is the source code, two clicks away and able to modified immediately. When pictures are helpful, they're there. Manuals include examples, offset from the main text.
There are clear, published guidelines for how to write documentation. I've found those generally helpful.
There are mailing lists which are excellent documentation. The rules for participating, such as avoiding top posting and organizing topics in threads, aid comprehension and accessibility. The mailing list documents why decisions are made. They document the history of an idea.
If you've ever wondered why some people are fanatical about Emacs, an underlying reason is that information about it is really easy to get at and is accessible.
It provides multiple layers of documentation along multiple dimensions.
Say you're an end-user. Where do you start? Maybe you read the tour on the webpage. Maybe you watch one of the countless videos. The first time you open Emacs, your cursor is on a link to the tutorial. The tutorial is interactive and allows you to save and continue later. The system sets you up for success in learning.
The tutorial leads you to the manual, written in Texinfo which is published in multiple formats. Within Emacs, you can use the info browser (you can access the same from the terminal outside of Emacs) to search and navigate the documentation. All manuals and references are also published to Html (as single page to facilitate searching terms across sections), as well as PDF and bound paper copies (available from the FSF). There is no single interface to the documentation. The interface can be a web browser, the info browser, your thumb on a physical page, etc.
Info/texinfo is amazing. Documentation is indexed. This allows you to search for terms, as well as section headers and keywords. If a term doesn't appear explicitly within the text or within your current document, it may be included as an index. What would fail in the pdf or html is found this way. You can search across documents (for example, the user manual vs. the programming reference). The apropos function even compiles search results as a table of contents.
Navigation of the documentation is robust. Forward, backward, up, down, top. Within Emacs, this is even better. There are lookups for functions, variables, and symbols. Lookups within the various documents (manual, reference, do strings, etc) is quick and integrated. Because the cost/pain of lookup is low, as well as terms indexed, separate documents feel like one.
Each function and variable has a quick-to-access docstring. The docstring may include links to other useful features or reference to other documentation. Documentation always has a link to the source code.
A lot of what I've said addresses the interface to the documentation. It's also important to consider the use-cases for the documentation and its intended audience. There are tutorials to introduce high level concepts (assuming zero prior knowledge), there are references for in-depth explanation of component details, there are docstrings to explain specific functionality, and there is the source code, two clicks away and able to modified immediately. When pictures are helpful, they're there. Manuals include examples, offset from the main text.
There are clear, published guidelines for how to write documentation. I've found those generally helpful.
There are mailing lists which are excellent documentation. The rules for participating, such as avoiding top posting and organizing topics in threads, aid comprehension and accessibility. The mailing list documents why decisions are made. They document the history of an idea.
If you've ever wondered why some people are fanatical about Emacs, an underlying reason is that information about it is really easy to get at and is accessible.