Re: Coordination for developer documentations

[Stefan Sauer <ensonic hora-obscura de>]

On 03/04/2014 07:05 PM, Frederic Peters wrote:
> 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).
I am trying to keep the gtk-doc manual up-to-date, also wrt to how to
document things. Bug report and patches are very welcome. I know that
wikis are easier to edit, but imho they are harder to find and less
often reviewed.
> > 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.
+1 for this. Someone overlooking this and making sure that efforts are
coordinated would be great.

Stefan
>         Fred
> _______________________________________________
> desktop-devel-list mailing list
> desktop-devel-list gnome org
> https://mail.gnome.org/mailman/listinfo/desktop-devel-list