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

[Frederic Peters <fpeters gnome org>]

Allan Day wrote:

> 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

I would tend to put goals before technical details, but library-web as
it is nowadays is certainly not the best option; I addressed a few of
the issues in my mail to gnome-doc-devel-list  


>  * 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.

There's some documentation, and it's even up-to-date up to the point
that several persons got it running locally, but it has a long
hack/build cycle by default (as it will cover all modules from
multiple GNOME releases), and is using XSL transformations, and many
persons find this arcane.

That structure made sense back in the day (2006) but given the way
other tools evolved (gtk-doc, yelp-tools), and better sysadmin
infrastructure (it was difficult to get new packages installed on the
RHEL version that was used until recently), it should be done
differently now.


>  * 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.

I gave my opinion in that previous email, "I'd go with a dynamic
website, as this would solve the issue of stale files, and offer
better ways to integrate important things, like search."

  (the stale files issue is the problem Jasper talked about, we get
   Google indexing files way suboptimally)


>  * 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).

There are several layers here, most of the documentation still comes
from C files, via gtk-doc, then from docbook, gtk-doc again. This is
the bulk of what gets published, even for more "textual" content
(migrating from GTK+ 2.x to GTK+ 3 for example); then we have other
HTML generators, like Doxygen for the C++ bindings. The other
documents, the Mallard pages in the platform overview or developer
demos, the few wiki pages, are a really tiny part.


But to be honest, while the workflow can definitely be improved, I
don't think it's the main obstacle. I look at user documentation, it
gets written, it gets updated, and it's Mallard in git repositories.

No, I think the obstacle is that we don't have enough people willing
to work on developer documentation over something else, even though
many will recognize the importance it has. It's not new.



        Fred