openoffice-doc mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Rob Weir <robw...@apache.org>
Subject Re: Make the IDL Reference a live documentation
Date Mon, 14 Jan 2013 19:20:48 GMT
On Sun, Jan 13, 2013 at 10:38 PM, Alexandro Colorado <jza@oooes.org> wrote:
> On 1/13/13, Andrew Douglas Pitonyak <andrew@pitonyak.org> wrote:
>>
>> On 01/13/2013 03:37 PM, Alexandro Colorado wrote:
>>> On Sun, Jan 13, 2013 at 2:07 PM, Andrew Douglas Pitonyak
>>> <andrew@pitonyak.org <mailto:andrew@pitonyak.org>> wrote:
>>>
>>>
>>>     Are you advocating something like doxygen? I would love it if we
>>>     did that! :-)
>>>
>>>
>>> Well I dont really know doxygen, but like I mentioned just having a
>>> commenting system under the reference could help users get further
>>> clarification on the use of each element, I think.
>>>
>>> I watched some videos of doxygen but they focus too much on the
>>> generation of documentation from code, which is a different thing all
>>> together.
>>
>> So you are not advocating inserting the documentation into the code to
>> tell people how to use the code. You just mean create something that
>> will generate the documentation.
>
> I am advocating inserting annotations in the documentation by regular
> users. Something that doesnt change the structure or the content but
> can add comments to it. For example something like this:
>
> http://imagebin.org/242811 and http://imagebin.org/242812
>

OK.  We might be able to do this.  Infra recently came out with a new
commenting system that integrates with the CMS.

https://comments.apache.org/

It allows public comments, but also moderation by committers.

We briefly discussed it a while ago, but were concerned that putting
it on prominent pages like home or download would lead to pure chaos,
spamming, vandalism, etc.  It is probably not possible to manage this
for pages that get 100K visits/day.  But if we used it in a limited
way, on API pages, then this might be work better.

In any case, take a look at the above link and see if it sounds like a good fit.

-Rob


>>
>>>
>>>
>>>     On 01/13/2013 09:45 AM, Alexandro Colorado wrote:
>>>
>>>         For the longest I have been having the desire to have a live
>>>         documents on
>>>         the IDL Reference. For people that don't know what I am
>>>         talking about is
>>>         the documentation of the API objects that are supported by
>>>         AOO. [1]
>>>
>>>         I have been wishing for an annotation property so users and
>>>         developers can
>>>         add annotations to the various API Elements and code that
>>>         could be used by
>>>         newcomers. Something similar to what PHP documents have. [2]
>>>
>>>         With technologies such as AJAX and JQuery, I think this should
>>>         be very
>>>         simple to do for anyone with enough experience on web
>>>         development. For the
>>>         longest time the activities of what happens in the community
>>>         has been
>>>         somewhat alienated from the website. For example, there are
>>>         tons of
>>>         snippets on the Forums, yet none of them make it to the site
>>>         (or the
>>>         application for that matter). Looking at the SDK this morning
>>>         I notice
>>>         there is almost no mention of PyUNO while the forum is filled
>>>         with snippets
>>>         of this bridge[3].
>>>
>>>         My thought process is that by allowing this documentation to
>>>         be more social
>>>         it will also connect the dots for new development to happen.
>>>
>>>         [1]
>>>
>>> http://www.openoffice.org/api/docs/common/ref/com/sun/star/module-ix.html
>>>         [2] http://php.net/manual/en/function.strftime.php
>>>         [3] http://forum.openoffice.org/en/forum/viewforum.php?f=21
>>>
>>>
>>>     --
>>>     Andrew Pitonyak
>>>     My Macro Document: http://www.pitonyak.org/AndrewMacro.odt
>>>     Info: http://www.pitonyak.org/oo.php
>>>
>>>
>>>
>>>
>>> --
>>> Alexandro Colorado
>>> Apache OpenOffice Contributor
>>> http://es.openoffice.org
>>>
>>>
>>
>> --
>> Andrew Pitonyak
>> My Macro Document: http://www.pitonyak.org/AndrewMacro.odt
>> Info:  http://www.pitonyak.org/oo.php
>>
>>
>
>
> --
> Alexandro Colorado
> Apache OpenOffice Contributor
> http://es.openoffice.org

Mime
View raw message