gedit: Mallard Documentation Conversion

Welcome. This page provides an overview of the effort to rewrite gedit's documentation in the Mallard format.

As a part of ProjectMallard, the gedit documentation is being rewritten in the Mallard format. All contributions are very welcome - check below for ways in which you can help out. Note that contributions are licensed under a CC-BY-SA 3.0 license. More info available here

Getting Started

• Check out the Mallard website to learn how to code in Mallard. The Ten Minute Tour is a great place to get started.

• Check out the Contact section for information on people to contact if you have questions about joining.

• We recommend joining the gedit mailing list. Discussion about gedit development takes place there, and you can submit ideas or ask for feedback there as well.

• You can check out the work we've already done here. Feel free to jump right in and start submitting patches if you wish.

• Most of all: Have fun!

Coding Guidelines

We've set up a few coding guidelines for the gedit documentation. These guidelines are not necessary to follow while contributing, but they can be helpful for keeping the code base clean. The most important guideline is that you should try to keep your code simple and readable. While we're not terribly picky about the formatting of the code, this guideline should super-cede all others, should you wish to follow it.

Some other optional, but helpful guidelines to help encourage consistency across the code base are as follows:

Nest tags

IE: Rather than

<tag1>
<tag2>
<tag3>
<tag4>
</tag4>
</tag3>
</tag2>
</tag1>

• try and shoot for

<tag1>
  <tag2>
    <tag3>
      <tag4>
      </tag4>
    </tag3>
  </tag2>
</tag1>

for readability. The first format leads to confusion about the relationships of tags to their parent folders and sub folders, while the second format makes it clear which tag belongs inside or outside of other tags.

End self-closing tags with a space

IE: Rather than <tag/>, we recommend <tag />. This helps keep the tag a little more readable and less cluttered. Not necessary to do, but helpful if you wish to do this.

Don't use too many <revision> tags

Since the history of the documentation's source code is managed by Git, revision information is already maintained. So it's a bit redundant to include version information in both places.

TODO

Define

• A target audience

- Thinking it should primarily be those a bit above beginners (casual users likely won't use text editors very often). My suggestion: At a minimum, for those who write web/markup languages, to serious programmers. System administrators also? ~Daniel Neel - Not sure about this, I agree that should be for beginners but also for serious programmers. I.e there are still some advanced features that I don't know how to use, and would be good to have in the help. Also something for medium programmers to help them on getting started to write a plugin etc would be great. ~Nacho

• Decide an appropriate tone for the documents, based on the target audience

• Decide what to include in the manual, what not to include (Some work done here)

• What needs to be done for release - what needs to be done for the documents to be considered complete?
• Once some good progress is made, start looking into getting the documents reviewed by other teams?

Done

• Setup the project on Gitorious (here)

• Set optional coding guidelines

Useful Links

• The GNOME Documentation Project

Contributors

Contact

Feel free to contact Jim or Daniel (in the contributors list) with any questions about getting started - we're glad to help! You'll also find both of us in the #docs channel on GNOME's IRC server.