Re: Coordination for developer documentations

[meg ford <meg387 gmail com>]

On 7 March 2014 17:45, meg ford <meg387 gmail com> wrote:
> It would also be awesome if whoever takes the lead on this makes sure that
> the functionality we are documenting actually works. If we want devs to be
> able to write GNOME apps then having documentation that matches the
> functionality they can access using the the language application developer
> docs are showing seems pretty key to me.

Sure, this is one of the main motivations for rebasing the
documentation generator on top of introspection data.

There are situations where bindings exist and in fact the functions don't work or the return values need to be accessed in odd ways (for example as by array index). Of course having the documentation is helpful because at least you don't have to mentally translate from C or read the raw gir files in order to figure out if the function should work, but there are some situations in which the documentation will need to be altered to reflect the reality.

Regards,

Tomeu

>
> On Fri, Mar 7, 2014 at 8:06 AM, Tomeu Vizoso <tomeu sugarlabs org> wrote:
>>
>> On 4 March 2014 16:58, Frederic Peters <fpeters gnome org> wrote:
>> > Hey,
>> >
>> > It's been proved again in recent hackfests, we have a really great
>> > team writing user documentations, and thanks have to be given to
>> > Shaun, and now Kat, for coordinating the effort.
>> >
>> > On the other hand we have absolutely no coordination for developer
>> > docs, I maintain developer.gnome.org with the little time I have,
>> > Aleksander helps with Devhelp, there are some punctual changes from
>> > various persons, David maintains gnome-devel-docs, Tomeu did work on
>> > generating python documentation from gobject-introspection a while
>> > ago, Giovanni did it for gjs recently, Jon improved markdown support
>> > in gtk-doc, etc. but all this happens without coordination and it
>> > happens people step on each other's toes, and it hurts.
>> >
>> > Developer documentation will be a topic during the Developer
>> > Experience Hackfest, but I believe we will fail again to provide
>> > lasting effects if nobody takes on a coordination role.
>>
>> I agree coordination is needed right now. I have signed up for the
>> hackfest because I know that there's still lots of work to do in the
>> api doc generator and I would like to put my experience on the
>> existing codebase to good use.
>>
>> But I'm a bit lost since the decisions that were agreed at the Berlin
>> hackfest seem to have been overridden at some point and I have missed
>> the rationale.
>>
>> > So, are you interested?
>>
>> These days I do stuff that is related only peripherally to GNOME, so
>> I'm afraid that I won't find enough time to take on the coordination.
>> If nobody gets to propose a good plan before, I guess we'll have to
>> have a good planning session at the start of the hackfest.
>>
>> Regards,
>>
>> Tomeu
>>
>> >
>> >         Fred
>> > _______________________________________________
>> > desktop-devel-list mailing list
>> > desktop-devel-list gnome org
>> > https://mail.gnome.org/mailman/listinfo/desktop-devel-list
>> _______________________________________________
>> desktop-devel-list mailing list
>> desktop-devel-list gnome org
>> https://mail.gnome.org/mailman/listinfo/desktop-devel-list
>
>