Re: Coordination for developer documentations

["Jasper St. Pierre" <jstpierre mecheye net>]

The issue seems to be that people show up, write a bunch of tutorials, docs, build a website, and then never finish it. They just leave and we're left with a half-finished developer docs site.

Usually, the tutorials that these guys write end up not compiling or running in newer versions of the GNOME development stack. So, we need to be testing them better.

Having such tutorials somewhere in some git repo so they can be easily tested would be a huge help.

Matthias's "application1-10" he did for the last GUADEC were excellent, but they're not quite "beginner" enough.

While I'd love to step up and do this, I'm remarkably busy as a person, and honestly, most of my free time is actually playing around with the web technology stack, not ours. It's a lot more exciting, and has a lot more fast-developing and approachable features.

(This last weekend I wrote some a simple 3D pong clone using WebGL, and then made it into a rhythm game with a dynamic sequencer using the Web Audio APIs. This sort of tech is ten times more exciting than whatever's coming in GTK+ next cycle, and I prefer to play with fun tech in my free time.)

On Tue, Mar 4, 2014 at 1:05 PM, Frederic Peters <fpeters gnome org> 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).

> 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

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

--
  Jasper