1. Developer Docs

Notes from conversations about developer documentation at the 2014 winter docs hackfest.

1.1. Current Situation

Existing issues with our developer docs and developer.gnome.org website:

• It's hard to hack on developer.gnome.org, and hard to get web hackers involved.
• There's a lack of clear focus on the needs of new application developers.
  • Current "platform overview" isn't the best way of presenting the material we have (there is some good stuff in there).
  • Variety of material on the existing website - different languages, audiences, etc. Some is targeted at new programmers rather than developers who are new to GNOME.
• We're not generating much useful content for developer.gnome.org.
• developer.gnome.org isn't very useful as a way to access all our resources - it doesn't work well as a portal.
• Most of our documentation writers don't have the expertise to write developer docs - if we want to produce new material, it will have to come from existing developers.
• Existing tools for producing developer documentation aren't friendly to occasional contributors - combination of Mallard, Git and patch review makes contributing documentation too expensive.
• Ryan's HowDoI documentation has had some success in generating new developer docs. Pages have been written by a number of developers: demonstrates how a combination of accessible tools (in this case the wiki) and atomic/narrowly scoped docs can encourage contribution.
• Limited resources are a significant factor, both in terms of system administration and tool creation, as well as documentation authors.

1.2. Requirements & Goals

A GNOME developer website needs to do the following things:

• Be a single portal for our various developer resources (hand-written tutorials, api reference documentation, HIG).

• Needs to be easy for people to contribute hand-written content (ie. not Mallard, Git & patch review).

• Needs to be focused on new GNOME app developers, and consistently target the same audience.
• Needs to be possible to view different API reference and HIG documentation by version number.
• Ideally, would be able to subscribe to and download API reference and HIG documentation.

1.2.1. Possible Non-goals

• Translatable documentation might not be in scope (we don't translate developer documentation currently).
• Could be difficult to build a highly integrated site, considering the variety of the existing material involved.

1.3. A Tentative Design

One possible approach would be to create a new site with the following components:

1. A simple home page, possibly made with plain HTML (eg. developer.gnome.org).
   • This would provide details about the various resources and link to other parts of the site, each built with existing technologies.
2. Getting started tutorials - stored in Git and put online using library-web (eg. developer.gnome.org/Tutorials).
   • This would incorporate the GTK+ Getting Started tutorial.

   • Other possible tutorials: setting up a development environment, overview of GNOME developer tools (DevHelp, Glade, Git, etc).

3. HowDoI tutorials, hosted on a wiki instance (eg. developer.gnome.org/HowDoI).
   • The wiki would be a place for developers to write short, focused tutorials.
   • Existing content from the developer docs could be moved to this space.
4. API Reference, generated using library-web (eg. developer.gnome.org/Reference).
5. Human Interface Guidelines, stored in Git and put online using library-web (eg. developer.gnome.org/HIG).

This is a hybrid approach, and would lack some integrated features like search. However, it would be feasible and could be used as a way to generate content for a more integrated site. Hopefully it would be possible to leverage existing MoinMoin infrastructure.

Possibilities:

• A common header that would allow navigation between sections of the site.

Possible issues/questions:

• How to handle tutorials for different programming languages on a wiki?
• Need to establish a clear set of guidelines for the wiki.
• Need to have active maintanence of the wiki (to keep it focused and consistent).
• Would the wiki element of the proposal

1.4. Comments / Questions

• FredericPeters:

  • I had forgotten about it but library-web already has support for integrating wiki pages (added in May 2011), for example: https://developer.gnome.org/Gnome3PortingGuide/ is automatically created from https://wiki.gnome.org/DevGnomeOrg/Gnome3PortingGuide, there is also https://developer.gnome.org/ProxyConfiguration/

  • actually all wiki pages listed in https://wiki.gnome.org/DevGnomeOrg will automatically get their counterpart on developer.gnome.org