Re: [api-dev] API documentation and improving interactivity
2010/9/6 Jürgen Schmidt juergen.schm...@oracle.com Hi Alexandro, thanks for picking up this topic immediately. Whatever we think will be an appropriate solution to provide an easier way how users can give feedback. I would suggest that we create a tool that use the input from the IDLs (the generated type library) as input and produce based on this info whatever is necessary. Do we have this tool already? How does the current documentation gets form? AFAIK the UNO interface is atomic and this will provide far too many items. Follow up please only on one list - dev@api.openoffice.org Juergen On 9/5/10 10:37 AM, Alexandro Colorado wrote: Hi during OOoCon a conversation started about the lack of examples on the API documentation as far as contributions goes. Basically there are several places where to go to: - API Documentation - CodeSnippets - Developer Guide - OOo Wiki The main issue is that users and readers have low accessibility to introduce examples or comments on the documentation. There have been some possible solutions discussed: - Move the API Docs to the Wiki - Version the API Docs depending on the OOo version - Close codeSnippets or move it to a technology that allow users to just paste snippets directly on the site As always the issue becomes lack of resources, time and information. My feeling is that if we air this topic with possible solutions would help us find better solutions. I do have a small script that allow me to clean off the documentation from the collabnet HTML and just isolate the HTML snippet. My next step could be to find a converter from HTML to a wikilang that allow us to easy publish it on the wiki and publish it on the wiki as a service (batch upload). Help is welcomed. - To unsubscribe, e-mail: dev-unsubscr...@api.openoffice.org For additional commands, e-mail: dev-h...@api.openoffice.org -- *Alexandro Colorado* *OpenOffice.org* Español http://es.openoffice.org
Re: [api-dev] API documentation and improving interactivity
Alexandro, you may want to look into http://www.ooocon.org/index.php/ooocon/2010/paper/view/196, once the slides are made available online by Peter (he has been doing a lot of work and needs probably more time to process all of the slides of the numerous presentations at this year's OOoCon, all in all, an incredible time-consuming task). UNO API Info is a tool that allows to gain documentation on the fly from any OOo programming language by either supplying the name of an IDL type (the fully qualified name e.g. of a service, an interface, a constant group, etc.) or by supplying any UNO object which then gets documented using reflection (which programmatically can be very challenging as you write yourself). The result is a writer/pdf document that has all the information formatted in a nice manner (members sorted by name, members sorted by type and name, constants sorted by name, depicting their values, properties sorted by name giving their type and attributes like maybevoid and the like, etc.) and also linked directly to the OOo documentation on the web. This way one can get an overview of all the functionality that is available, and for further documentation you just follow the links of those types/members that you are interested in. Finally, one can also have not only a single IDL service, interface or single UNO object documented, but also the members they contain (layer: 2). If you point your browser to http://wi.wu.ac.at/rgf/rexx/misc/OOoCon/2010_Budapest/, then you'll get to see example PDFs that got generated on the fly by supplying the UNO object representing a writer object (which interestingly implements more than one service). This is a somewhat extreme example, which also demonstrates how much functionality is at the hands of a programmer of the writer component. However, it also demonstrates how documentation can be devised that lets one see the forest (instead of the many trees making up the forest) too. At this OOoCon I also presented this live, demonstrating how to use this facility among other languages from JavaScript and Python. There is a readme/documentation of the tool at http://wi.wu.ac.at/rgf/rexx/misc/OOoCon/2010_Budapest/read-me-UNO_API_info.html.pdf, which documents this utility (including code to demonstrate how to use it from Basic, Java, ooRexx as well). The tool is not meant as a replacement for XRay and relatives, but as an additional means of on-the-fly-documentation generation with overview character to help the programmers mastering their challenging work. If you (or anyone else) have (has) any questions/comments regarding this tool, then please just post them via this list. HTH, ---rony On 10.09.2010 16:19, Alexandro Colorado wrote: 2010/9/6 Jürgen Schmidt juergen.schm...@oracle.com Hi Alexandro, thanks for picking up this topic immediately. Whatever we think will be an appropriate solution to provide an easier way how users can give feedback. I would suggest that we create a tool that use the input from the IDLs (the generated type library) as input and produce based on this info whatever is necessary. Do we have this tool already? How does the current documentation gets form? AFAIK the UNO interface is atomic and this will provide far too many items. Follow up please only on one list - dev@api.openoffice.org Juergen On 9/5/10 10:37 AM, Alexandro Colorado wrote: Hi during OOoCon a conversation started about the lack of examples on the API documentation as far as contributions goes. Basically there are several places where to go to: - API Documentation - CodeSnippets - Developer Guide - OOo Wiki The main issue is that users and readers have low accessibility to introduce examples or comments on the documentation. There have been some possible solutions discussed: - Move the API Docs to the Wiki - Version the API Docs depending on the OOo version - Close codeSnippets or move it to a technology that allow users to just paste snippets directly on the site As always the issue becomes lack of resources, time and information. My feeling is that if we air this topic with possible solutions would help us find better solutions. I do have a small script that allow me to clean off the documentation from the collabnet HTML and just isolate the HTML snippet. My next step could be to find a converter from HTML to a wikilang that allow us to easy publish it on the wiki and publish it on the wiki as a service (batch upload). Help is welcomed. - To unsubscribe, e-mail: dev-unsubscr...@api.openoffice.org For additional commands, e-mail: dev-h...@api.openoffice.org
Re: [api-dev] API documentation and improving interactivity
On Fri, Sep 10, 2010 at 9:48 AM, Rony G. Flatscher rony.flatsc...@wu-wien.ac.at wrote: Alexandro, you may want to look into http://www.ooocon.org/index.php/ooocon/2010/paper/view/196, once the slides are made available online by Peter (he has been doing a lot of work and needs probably more time to process all of the slides of the numerous presentations at this year's OOoCon, all in all, an incredible time-consuming task). UNO API Info is a tool that allows to gain documentation on the fly from any OOo programming language by either supplying the name of an IDL type (the fully qualified name e.g. of a service, an interface, a constant group, etc.) or by supplying any UNO object which then gets documented using reflection (which programmatically can be very challenging as you write yourself). The result is a writer/pdf document that has all the information So how can we make this documentation Read/Write instead of just Read Only. By that I mean that users can share examples and not just the documentation of the service. What many users have been asking for is a way that we can edit and put example uses of the services. And to be able to manage those commentaries and notifications within the same documentaion. An example of that is the information on the PHP documentation, althought many FLOSS projects have that property. A simple idea is to report to a wikilang instead of an odt/pdf and be automated the publication on the wiki. Also keep a version of the documentation so that the commentaries don't become obsolete although the problem with that is that many services still good might get lost. (Something to solve moving forward). formatted in a nice manner (members sorted by name, members sorted by type and name, constants sorted by name, depicting their values, properties sorted by name giving their type and attributes like maybevoid and the like, etc.) and also linked directly to the OOo documentation on the web. This way one can get an overview of all the functionality that is available, and for further documentation you just follow the links of those types/members that you are interested in. Finally, one can also have not only a single IDL service, interface or single UNO object documented, but also the members they contain (layer: 2). If you point your browser to http://wi.wu.ac.at/rgf/rexx/misc/OOoCon/2010_Budapest/, then you'll get to see example PDFs that got generated on the fly by supplying the UNO object representing a writer object (which interestingly implements more than one service). This is a somewhat extreme example, which also demonstrates how much functionality is at the hands of a programmer of the writer component. However, it also demonstrates how documentation can be devised that lets one see the forest (instead of the many trees making up the forest) too. At this OOoCon I also presented this live, demonstrating how to use this facility among other languages from JavaScript and Python. There is a readme/documentation of the tool at http://wi.wu.ac.at/rgf/rexx/misc/OOoCon/2010_Budapest/read-me-UNO_API_info.html.pdf, which documents this utility (including code to demonstrate how to use it from Basic, Java, ooRexx as well). The tool is not meant as a replacement for XRay and relatives, but as an additional means of on-the-fly-documentation generation with overview character to help the programmers mastering their challenging work. If you (or anyone else) have (has) any questions/comments regarding this tool, then please just post them via this list. HTH, ---rony On 10.09.2010 16:19, Alexandro Colorado wrote: 2010/9/6 Jürgen Schmidt juergen.schm...@oracle.com Hi Alexandro, thanks for picking up this topic immediately. Whatever we think will be an appropriate solution to provide an easier way how users can give feedback. I would suggest that we create a tool that use the input from the IDLs (the generated type library) as input and produce based on this info whatever is necessary. Do we have this tool already? How does the current documentation gets form? AFAIK the UNO interface is atomic and this will provide far too many items. Follow up please only on one list - dev@api.openoffice.org Juergen On 9/5/10 10:37 AM, Alexandro Colorado wrote: Hi during OOoCon a conversation started about the lack of examples on the API documentation as far as contributions goes. Basically there are several places where to go to: - API Documentation - CodeSnippets - Developer Guide - OOo Wiki The main issue is that users and readers have low accessibility to introduce examples or comments on the documentation. There have been some possible solutions discussed: - Move the API Docs to the Wiki - Version the API Docs depending on the OOo version - Close codeSnippets or move it to a technology that allow users to just paste snippets directly on the site As always the issue becomes lack of resources,
