Re: Coordination for developer documentations

[Allan Day <allanpday gmail com>]

Frederic Peters <fpeters gnome org> wrote:
...
> > 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.
...
> 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.

Right: continuity seems to be one of the main issues we've had in
recent years. Contrary plans have been made at various hackfests,
often by separate or partially overlapping groups of people. We've
also had individuals come in, make changes and then move on to other
things.

The Dev X hackfest will be a great opportunity to deal with some of
this. We've made an effort to get a wide range of participants at the
upcoming Dev X hackfest, including members of the documentation and
GTK+ teams, so it will hopefully be a chance for everyone to get on
the same page.

We should also make sure that we agree on a single place to keep our
documentation plans, so we don't keep reinventing the wheel each time.

> > So, are you interested?

I can see coordination happening at a few levels. As already
mentioned, we need a shared plan. This will need to include things
like:

 1. Designs for developer.gnome.org.
 2. A structure and format for handwritten tutorials.
 3. API reference documentation roadmap.

One really positive thing we can do is agree on a single place to keep
designs and plans for developer docs, possibly in a new space on the
wiki. We should also talk about when and how to update these plans, so
that everyone is kept in the loop.

To be honest, a large part of the coordination burden needs to fall on
the people who are working on the toolkit - since they know how the
platform is developing, they need to be able to update the handwritten
docs or indicate when things need updating or adding. In short: any
plan we come up with will have to address how we are going to close
the gap between platform and docs.

Allan