FLOSS Manuals
Editing Overview
Editing manuals is where all the fun begins! Free documentation writing should be an enjoyable experience, so focus on a task you think is fun and get started. You don't have to 'think big' when making a contribution, every edit helps. Making the images better, improving layout, spell-checking, laying out the print-on-demand manuals, rewriting a sentence, or adding whole chapters or manuals are all tasks that help improve the manuals. So pick something that appeals to you and go ahead and do it.
The best way to learn how to contribute is to jump in and do it. Don't worry about making mistakes, just get stuck in and edit away. If you make a mistake someone else will spot it and correct it later.
If you are worried that errors will put readers wrong, then don't worry! All edits to the manuals are not 'live' but are filtered through a simple publishing process where edits are checked before they go into the final manual.
FLOSS Manuals is about creating good documentation, but we are also about participation and collaborative knowledge building. There is a community involved in producing the manuals, and if you want to discuss issues then consider joining the mailing list:
http://lists.flossmanuals.net/listinfo.cgi/discuss-flossmanuals.net
WRITE
The WRITE section (http://www.flossmanuals.net/write) of FLOSS Manuals is where all the manuals are located for editing.
You can see two basic sections of this page. On the left is the navigation bar and on the right is the content window. In the example above the content window is displaying the WRITE home page. You can see a list of manuals under the title MANUALS:
By clicking on any of these titles you will be taken to the 'Home page' for that manual. If I click on the GIMP manual I will see something like this:
This page contains the information about the GIMP manual. Notice this page is not the page that the reader sees if they clicked on GIMP from the READ section (the front page of FLOSS Manuals). The actual GIMP manual looks like this:
The above is the 'published' version of the GIMP Manual. You might ask 'why there are two versions of the manual?' Well, all manuals have a development version and a published version. The development version may contain half finished edits, chapters that have not yet been included in the final manual, material that needs to be spell checked etc. It is not nice for readers to see all this, so when all the edits and spell checking etc is done these changes get copied to the manual the reader sees.
The development version, where you make all the edits, is kept in the WRITE section, and the readable version is kept in the READ section. If a manual does not have a version in READ it means it is not yet ready to be included there and more work needs to be done.
Having the two different versions like this also means that you shouldn't be worried about making mistakes when editing manuals. The reader will never see these mistakes.
Chapters
Every manual is made up of chapters. When you edit a manual you are actually editing a chapter within that manual. Chapters can be accessed for editing through the manual's WRITE home page (lets call this the manual's 'homepage'). If I look at the example of the GIMP homepage I can see that there is a list of chapters :
I can see three columns. The first column contains the name of the chapter. This name is linked to the editable version of the chapter. If I like I can edit the chapter directly by clicking on the 'edit' in the next column. In the final column is text from the first sentence in that chapter.
The name of each chapter is written using a system common to many wikis called 'camel case'. A camel case is a compound word (one or more words joined together) without spaces and the first letter from each word is capitalised. For example, instead of 'Installing Windows' we have 'InstallingWindows' etc.
Chapter names are displayed in camel case only in the WRITE section. When a new version of a manual gets copied to the READ section these titles are changed to something more reader-friendly. Also note that the list of chapters above contain chapters not in the version of the manual in READ and also that they are in a different order. Choosing the right names for each chapter, deciding which ones to include and exclude, and putting them in the right order is the job of the manual's Maintainer.
Maintainers
Each manual has a Maintainer. A Maintainer is someone that keeps an overview of the manual. Their job is to keep an eye on quality, communicate with people contributing to the manual, and publish the most recent 'readable' version of the manual as necessary. If you are contributing to a manual it is nice to keep in touch with the manual's Maintainer, but it is not necessary. You could just edit away without ever being in touch with the Maintainer. However the Maintainer is the central point for all information about the manual so it can be useful to drop them a line (especially if you create a new chapter and want it included in the manual). If you wish to contact the maintainer for a specific manual then join the FLOSS Manuals mailing list (and ask who the maintainer is) : http://lists.flossmanuals.net/listinfo.cgi/discuss-flossmanuals.net