Notes from conversations about developer documentation at the 2014 winter docs hackfest.
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.
- 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:
- 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.
- 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).
- 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.
- API Reference, generated using library-web (eg. developer.gnome.org/Reference).
- 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.
- A common header that would allow navigation between sections of the site.
- 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
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