Friday, February 19, 2010

Mallard Documentation


GCalctool now has a new help document in Mallard format. This is my second Mallard document I've written, the first was the help for Simple Scan.

Wow. Mallard is really, really easy to use!

Mallard documents are topic based which basically means writing a few paragraphs on each activity your readers can do with your application (like how to use trigonometric functions or an automatic document feeder). I wrote the topics over a week with a text editor and marked them up at the end.

Testing is great. Just run yelp with the directory the files are in to browse the documents immediately.

If you want to contribute, take the ten minute tour, pick your favourite GNOME application, ask if they've got documentation that needs updating and get writing!

(I recommend starting by copying an existing document; I used the gbrainy help as a basis for the Simple Scan and GCalctool help).

6 comments:

William Chambers said...

Looks pretty awesome. Always good to see new documentation options. Though it'd be nice if it wasn't just a gnome project as without serious cross-platform support I can't really consider it.

Jordi Mas said...

Hello Robert,

In gbrainy when you do autogen.sh there are a few warnings since I integrated Mallard.

Have you come across the same issue? I tried to fix them but I could not determine the root of the problem.

Regards,

Jordi Mas
jmas at softcatala.org

Shaun McCance said...

William, we certainly don't intend for Mallard to be a Gnome-only solution. It was initially developed within Gnome, so Gnome is of course the first major adopter. But we're steadily working towards letting Mallard fly on its own. Just give us a chance to get our (webbed) feet wet. :)

Robert Ancell said...

Jordi, haven't seen a problem yet.

Unknown said...

Defaul yelp hangs my computer when i trying to browse gbrainy docs... 100% cpu usage

id scanner said...

Pretty good article ! I enjoyed reading about Mallard. Mallard Documentation is looking to be useful for business purpose as you said Mallard documents are topic based which basically means writing a few paragraphs on each activity. I will surely go for it.