This site has been retired. For up to date information, see handbook.gnome.org or gitlab.gnome.org.


[Home] [TitleIndex] [WordIndex] 

Developer Guides

This page outlines documents that we should have for developers. It includes documents that we do have, to get a complete picture. Each guide addresses a topic, so it's easy for developers to find the information they're looking for. Do not fear small articles. Do not fear redundancy. Do not fear inter-linking. See also the related page IdealDeveloperDocumentation.

Other topics that may be useful but aren't yet listed here are performance tuning, maintainer tasks, working with our buld utilities and the autotools chain, and packaging guidelines.

This is a wiki. Do add your thoughts.

What We Have

Overview of the GNOME Platform

This is a brief overview of our technologies. Nearly every other guide on this page could be referenced from this document, because it touches briefly on every topic. This is currently being worked on.

GNOME Documentation Style Guide

We have this, but it's showing its age. It hasn't been actively maintained, and it hasn't seen any major updates in quite some time. We should replace this by a GNOME Manual of Style, i.e. a style guide that does not bill itself as being specific to documentation. This should include various recommendations on language usage and a complete reference of recommended terminology. Documentation-specific stuff can still be included, as can interface-specific stuff.

Integrating existing software with GNOME

This document largely discusses interactions with the desktop, typically using freedesktop.org technologies. It is not intended to show how to develop a complete application, though it may provide some overview of parts of the platform. Mostly, this document should discuss things like the applications menu and the mime system. It should be realistic about older GNOME versions and other desktops and address common pitfalls. We've slowly been reducing the number of hoops ISDs have to jump through to play nicely on the desktop, but hoops remain. Be honest to ISDs about these. This should possibly be renamed to a simpler title, like Integration Guide.

GNOME Handbook of Writing Software Documentation

This is really out of date, and it never did address everything it should have. This should really provide everything writers need to know to write a typical document. This includes providing documentation on writing DocBook. This guide does not have to explain all of DocBook, only the parts that we consider relevant to typical user documentation. This document needs a better title.

Human Interface Guidelines

We have this, and it's a great document. But somebody please retake the screenshots. In light of the rest of these documents, we may want to update the HIG to point to other documents where they're relevant. In particular, the HIG should mention the Style Guide prominently, and defer to it for all questions of language and terminology. Calum Benson is in charge of the HIG.

What We Want

Accessibility Guide for Developers

This document exists in draft form at http://developer.gnome.org/projects/gap/guide/gad/ This document should be used in conjunction with the Gnome Accessibility Guide which discusses all of the accessibility technologies in our platform. It provides comprehensive documentation on how to make accessible applications, including tips on best programming practices. It does not go into detail about developing with libraries such as ATK. Rather, it provides an ATK overview and directs users to the complete ATK documentation.

Note that the GNOME Outreach Program: Accessibility has a task to work on this document at https://bugzilla.gnome.org/show_bug.cgi?id=519313

Internationalization Guide for Developers

This document discusses all of the internationalization technologies in our platform. It provides comprehensive documentation on how to make internationalized applications, including tips on best programming practices. It may be redundant with the Glib documentation, as gi18n is a fairly small piece of API. It may point to full documentation on upcoming packages like Giulia. Danilo and others have written such guidelines many times. We need to get it all together in a single document that developers can actually find.

Localization Guide

This document is largely intended for translators. The bulk of translators' work is just translating simple strings in simple applications. But there are plenty of much harder tasks. This document should introduce intltool and xml2po and explain how to work with them. It should discuss common internationalization facilities in our desktop, and in the underlying system. This guide should give everything translators need to know to go from new and unheard-of language to 100% supported.

Icon Guidelines

A document about icon style, and techniques for drawing consistent icons, would help considerably in ramping up new artists. This should include practical information as well as stylistic information, such as how to design for various accessibility needs. Jakob has the "High Contrast Accessible Icons" (http://jimmac.musichall.cz/old/high-contrast/index.xhtml) which has valuable information that could be merged here.

Build Tools Guide

Providing a basic rundown of how to use autotools, along with the things we provide that work with the build system: pkg-config, intltool, gtk-doc, gnome-doc-utils, autogen, etc.

NB: Some of this is already available in the GNOME 2 developer guide, as this is no-starch book and the copyrights owned by Miguel we should probably drop some of that info into the library

Some suggested developer guides that could be added to https://developer.gnome.org/guides

Custom widget guides

Using dialogs and creating custom dialogs

Adding printing support to your application

Creating a plugin system for your application

Other

Discussion?

IsmaelOlea: What about pushing this proposal as an freedesktop, or a similar one, recomendation? Obiously atomizing the platform specific items.

CategoryDocumentationProject

2024-10-23 11:04