|Subject:||Re: Opaque objects and Emacs documentation|
|Date:||Fri, 17 Jul 2020 14:26:27 +0000|
|User-agent:||Alpine 2.21 (NEB 202 2017-01-01)|
IMO the main goal of writing Emacs documentation (and software documentation in general) is not to help its users, but to help all those who in the future, when you will have moved to something else, will work on the code you wrote.So you have never encountered a difference between internal documentation and public documentation?
Of course I did. But as it happens, this difference does not exist in Emacs. Remember that one of the direct inspirations of Emacs were Lisp machines, in which the user can read and modify almost every piece of code on the fly, from the lowest to the highest level. In such a system, there can be no difference between "internal" and "external" documentation. I understand that it can be difficult to adapt to this way of thinking when one comes from another programming tradition.
The most valuable documentation is [...] that which describes original choices, and the reasons for them. Or an overview of how the system works. We're not discussing either of those options here.
It's one way to document things, but certainly not the only one. I'm not sure I agree that it's the "most valuable" one. When you have to work on code written by someone else, you rarely do so on the highest level, and having a picture of the overall organization is not directly useful. Having a clear and well-written documentation for each function is directly useful.
|[Prev in Thread]||Current Thread||[Next in Thread]|