Developer Docs

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

Contents

  1. Developer Docs
    1. Current Situation
    2. Requirements & Goals
      1. Possible Non-goals
    3. A Tentative Design
    4. Comments / Questions

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.

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.

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.

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

Comments / Questions

Hackfests/WinterDocs2014/DeveloperDocs (last edited 2014-01-30 13:41:31 by AllanDay)