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".
+1 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). > > 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. For example, the Calc Add-in documentation is from the stone age (http://wiki.services.openoffice.org/wiki/Documentation/DevGuide/Spreadsheets/Spreadsheet_Add‑Ins), I have developed several add-in, but I don't feel qualified to update the documentation. And there are sure several examples where you need to know the implementation in order to explain how something works; now I recall css.awt.XToolkit.createWindow/s http://api.openoffice.org/docs/common/ref/com/sun/star/awt/XToolkit.html#createWindow I only understood what was expected under the css.awt.WindowDescriptor after I studied some sources in the toolkit module. May be Clayton and/or Jürgen have some statistics about contributions in the Dev's Guide since it's been moved to the Wiki; but in general, the most I've seen is adding source tags for syntax highlighting, but no big contributions from community members. IMHO a Dev's Guide documentation writer has also to be a developer (I mean: not only an API client, but with the knowledge to dive in the source code), so an idea for improving this situation may be calling for documentation contributors who would then be mentored by a developer in the know of the implementation. Regards --------------------------------------------------------------------- To unsubscribe, e-mail: dev-unsubscr...@api.openoffice.org For additional commands, e-mail: dev-h...@api.openoffice.org
