Writing Documentation

Getting Started

If you haven't already, read through GettingInvolvedWritngDocs. It will tell you all you need to know to get connected to the team, get Jokosher and get started working on documentation.

Documentation Writing Resources

A good place to start is the GNOME Documentation Project (GDP) Resources page. The guides and templates there don't need to be memorized, but they are the ultimate authority in most cases. Specific resources from the GDP will be referred to below.

Wiki Editing

If you'll be working on documentation on the Wiki, read HelpOnEditing and SyntaxReference. Wiki markup is not as complicated as other markup languages, but you'll want to learn the details. You don't need to memorize all this, but check back from time to time to learn more.

If you are very new to Wiki editing, got to the WikiSandBox, edit the page and play around. Remember that changes can be undone, so experiment. When editing for real, make sure to use the Preview button to review your changes before you save.

Log in to the Wiki before editing. This is now mandatory. We will then be able to give you credit for all your hard work. Whenever possible, put a comment in for your change. When other developers are reviewing your changes they can get an overview from your comment rather than having to pull a diff on every page and compare line by line.

DocBook Editing

DocBook is similar in spirit to HTML, but different in purpose. It has many specialized tags for technical documentation, but almost no presentation formatting. The emphasis is on marking up the structure of the document, not the look. The GNOME help system takes care of all the formatting so you don't have to.

A good place to get started in writing DocBook is the GNOME Handbook of Writing Software Documentation. It has information on writing documentation in general, and goes over what you'll need to know about DocBook to get started. For a complete guide to all the details, see Norm Walsh's DocBook: The Definitive Guide.

HTML Editing

There are many resources and tutorials on the web for learning HTML, so not much detail will be given here. Feel free to add your favorite resources and tutorials to this page.

One resource is http://www.htmlhelp.org/.

We don't have a strict style for HTML, but be consistent with what has already been done. The HTML code needs to be simple, readable and maintainable, not fancy.

Creating Screen Shots

ScreenShots - a short tutorial on doing screen shots

Writing Style/Conventions

Documentation, like any other type of writing, is an art form. Art is an expression of the heart, but it can also be categorized into a particular style. Music is hard or soft, a painting is realisitic or abstract. The Jokosher documentation project does not have a particular style guide, but some basic guidelines apply:

Follow the Jokosher philosophy - simple, attractive, intuitive
Write to your audience - musicians and other audio artists who just want to get the job done, not technical gurus
Make simplicity the top priority Not only is simple clear language easier to understand, it's far easier to translate to another language.

Jokosher aims to be a GNOME application, so we use the GNOME Style Guide as a reference. Section 1, Fundamental Concepts of Technical Documentation, provides some tips to consider if you are new to technical documentation. At this early stage we are concerned more with getting complete, accurate documentation than with strictly following a style guide, but our ultimate goal is to comply with GNOME standards.

Wiki

Page

User