Message de Ariel Constenla-Haile date 2009-05-14 17:04 :
Hello Mathias,
On Wednesday 13 May 2009, 14:14, Mathias Bauer wrote:
The best documentation is an API that doesn't need one. This deals with
the fact that people don't like to read documentation. Having "speaking"
names for events is a good thing per se, not just some "language
aesthetics".
Yes, auto-documentation by correct naming is always better. But keep in mind
that vocabulary words can be ambiguous in a given language, can be wrongly
chosen by a non-english designer, and can be wrongly interpreted by a
non-english reader. To get rid of ambiguity you need further explanations, and
that is documentation.
Besides, it's true that people don't like reading documentation (and also that
developers in general don't like writing documentation).
We often see people asking questions without even reading first the API ref.
nor the Dev's Guide (and not even searching on the mailing list if the theme
has already been discussed), but this is a general problem I see also on other
mailing list (people have become simply more lazy).
I agree (sigh) and these people never achieve a code without help from those who
have spent time to read and understand the documentation.
It would be more useful to spend time on improving the API documentation
(IDL and Developer's Guide) and correcting known API issues.
Sure. But I think documentation can be done by anybody knowing about the
API, developers as well as users.
In general, that's not true. For writing serious documentation you need some
information about its implementation; but API user only know the specification
and how to use the API.
I have several remarks here:
- IDL documentation should be written by the developer, because only him/her
knows exactly the definition of the services, interfaces, properties etc that
he/she has designed. It should be as clear and precise as possible.
- IDL is not sufficient in itself, textual explanations and some illustrative
examples are necessary to understand the "philosophy" of an API. This initial
description should be written by its developer, in the Developer's Guide.
- Further explanations, hints, code examples in different languages, may be
added by API users, either in the Developer's Guide or in separate wiki pages
that should be linked from the Developer's Guide.
- An API user should not be compelled to read the code, this is contrary to the
principle of an API. Take for example the description of the parameters for PDF
export <http://wiki.services.openoffice.org/wiki/API/Tutorials/PDF_export>. This
fantastic page was written by Ariel, certainly after lengthy reading of the
source code. I think that most of it should have been written by the developer
in the Developer's Guide. Without this information, the PDF export API is
useless for an ordinary user. And the developer should update it when he/she
changes or adds parameters.
- An API user can find lots of things that are not documented, by playing with
the API and using introspection tools (Xray, MRI, etc). Understanding the API
through these tools is much easier than delving into the official documentation
(and not finding what you look for). The problem here is that the API user
cannot distinguish what is really part of the contract and what is un-intended
(but useful) behaviour of the API. So he/she may create user code based on a
feature that is not supported.
Regards
Bernard
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscr...@api.openoffice.org
For additional commands, e-mail: dev-h...@api.openoffice.org
