Developer Docs Roadmap [was Re: Glade release to include GtkHeaderBar?]

[Allan Day <allanpday gmail com>]

Frederic Peters <fpeters gnome org> wrote:
...
> Since the hackfest in Norwich in January it's possible to get specific
> modules online (almost) directly after the git commits.  It is
> configured that way for gnome-user-docs and gnome-getting-started-docs
> (for help.  gnome.org) and for gnome-devel-docs (developer.gnome.org).

Ah! That's good to know.

> A few months ago I posted some plans and questions to the
> gnome-doc-devel-list gnome org mailing list, but probably I should
> have asked people to subscribe there first :)  So here they are:

Yeah I'm subscribed, but I don't follow that list very closely.

> Support for multiple programming languages & multiple versions:
>
>   On a structure level, there are at least two important questions: what
>   kind of navigation do we want between programming languages (and
>   perhaps on a more fundamental level, how do we expose them?), and
>   between different versions of the libraries. At the time it was
>   important to have various versions available online, for exemple GTK+
>   2.6(?) was available because Nokia(?) used that version in their
>   developments, but today we may want to expose a more unified "this is
>   the current GNOME API" approach. (and that "bundle" approach would
>   also benefit devhelp)
>
> Covered libraries:
>
>   This brings the question of the libraries we want on the developer
>   website, it started as just our core libraries, but requests after
>   requests, it got its share of other libraries.  (but if we decide to
>   put them away, it's certainly also important to have a place for
>   them).

The design team can certainly work on a new look for the existing
site, along with how versioning could work, and we can turn this into
a roadmap. As a part of that, we can take a look at how the material
we have should be organised.

However, before we go down that route, it seems like we should at
least discuss whether library-web is the best option going forward. It
seems like there are a number of issues with the existing
infrastructure, which make me question whether we should be investing
in it or going for something new/different:

 * Hackability - from what I've seen, it is very difficult for people
to hack on developer.gnome.org. The barrier to entry is high,
documentation is lacking, and it all seems rather obscure.

 * User experience - we need to decide whether developer.gnome.org
should look and feel like a static website, or should be more like a
web app. I was looking at Read the Docs [1] a while ago, and that kind
of experience seemed like a good fit for API docs especially - search
is prominent, you can quickly switch between documentation, etc.

 * Documentation writing workflow. Monolithic modules written in
Mallard, like gnome-devel-docs, aren't approachable for developer
documentation writers. The HowDoI series has been reasonably
successful, partly because it is easy to write documentation on the
wiki, but finding and navigating that material isn't great [2]. A
middle ground might be appropriate (Markdown HowDoIs, perhaps).

Then there's the whole question of the tool chain required to generate
the API docs, which I'm not qualified to discuss...

Allan

[1] https://github.com/rtfd/readthedocs.org
[2] https://developer.gnome.org/guides#tutorials