Re: Coordination for developer documentations

[Frederic Peters <fpeters gnome org>]

Hi Allan,

Allan Day wrote:
> > So, are you interested?
>
> It would help to know a bit more about what you think this
> coordination role would involve. Are you concerned with keeping
> technical changes in step, for example, or is it more the content in
> our hand written documentation that we need to be careful about?

I was mostly concerned by our technical infrastructure for developer
documentation, but that itself has of course been driven by the
content we produced (or wanted to produce), so I don't think they can
really be separated.

A recent example is the way gtk-doc comments are written, and how to
accomodate them in order to provide meaningful comments when reused
for other languages (references to manual memory management for
example).


> Maybe the concerned parties just need to be made aware of how their
> work might affect others? Or maybe the dependencies between components
> need to be more clearly spelled out?

Given a vision I believe it will be necessary to coordinate whatever
needs to be done to get to it, having various persons giving the
subject a bit of their time sporadically won't work out (that's what
we've been doing since at least the Berlin hackfest more than four
years ago).

Maybe we do not need a person, maybe tools (like the gnome-devel-doc
list) are enough to get the required coordination, but from what I've
seen of the documentation team, a dedicated and focused person really
helps.

So I agree with you, the first is certainly to get that common vision
nailed down. But then, having a solid developer documentation team,
rather than various individuals, would help tremendously, in defining
the vision, and working towards it afterwards.


        Fred