documentation in Mallard format

[adam]

Shotwell's user guide is currently a Wiki page.  We should consider providing documentation in DocBook format at some point.  This is the documentation format used by most GNOME applications, and using it might possibly ease documentation translation.

[bthuree]

Same as #1869 (Providing a Gnome 3.0 help text in Mallard format)

[adam]

As bthuree mentioned in his comment, we should also consider Mallard as a format for the Shotwell documentation.

[dave]

Hi, I was wondering if any internal conversations have been had about whether to use Mallard or DocBook? as the official help format. I believe we left this on the mailing list talking about how official documentation should replace the wiki at some point but the Shotwell team was not sure about which format should be used.

Since starting the thread in the mailing list I've tried tackling another project with Mallard and have made some progress. It's not looking too hard to work with. I have not tried Docbook though.

One con I can think of with Mallard may be that the specs appear to still be in a draft stage and it is in a continuous state of evolution where as DocBook? does appear to be more mature and the specs finished.

Anyhow, this is just to get the ball rolling. I understand everyone is probably busy with .6 getting out. Good luck!

[adam]

Dave,

we've made no decision yet, and thanks for your patience with this.  Yes, we're currently focused on getting 0.6 out the door and we'll have a Mallard/DocBook discussion some time in the next week as we start planning 0.7.  There's no hurry, really, since Mallard and/or Docbook will be a 0.7 feature and we won't ship 0.7 until mid-August.  We'll let you know once we've chosen a direction.

[adam]

We've decided that we'd like Shotwell to have reference documentation in Mallard format for the upcoming (0.7) release.  We'd like to keep the Shotwell user guide alive and up to date as well, though, since it's nice to have documentation the user can read without having to follow hyperlinks all over the place.

Dave, are you still interested in working on the Mallard documentation and/or an updated user guide?  We're planning to release Shotwell 0.7 in just a couple of weeks, so we'd like to get started on the Mallard documentation soon.  If you are no longer available then we'll look for someone else to work on this.

[dave]

Hey Adam, I am still interested in working on this. I'll give it a go and see if I can make any progress. I'll admit I wish there were a bit more time though.

Would you like me to basically re-write the one on the web with updated content or are you looking for something else here? I'll admit I haven't fooled around with Shotwell in some time and I'm a fan of the way the material is written and organized online which leaves me wondering if it is best re-written in its entirety as is or scaled down so that it serves just as a reference.

Basically, I guess I'm looking for a direction to take this in. Given that I hope to come up with something to show fairly quickly to see if you like it or want it changed around.

[jim]

Hi Dave,

We are interested in preserving the current help page, although it might be available in another form at some point. (It might be we present to the user as a User Guide and let Mallard be the Help reference.) Certainly the current material would be a good resource to create Mallard content.

Paul Cutler (who's done a great deal of work in GNOME documentation) recommended this to me:

With that in mind, Mallard was written to do two things - focus on application (and topic based) help and be an easier syntax to write instead of Docbook. Docbook is great if you want to write a book or transform the document into a web page, html etc, but application help doesn't need all of its features.
As far as starting the process or opening a ticket, I would encourage you, as a first step, to brainstorm what the topics that should be included are. It's no different from any other form of writing - the planning is the most important (and usually most difficult) part. For Shotwell - "importing photos", "editing photos", "export photos" (when it has that feature) etc. From there you'll get some logical groupings and sub-topics.

He also suggested looking at Empathy as an example, which uses Mallard.

So I think the first step in this process is to come up with a list of topics/tasks that are grouped into logical sections. (I'm looking at Empathy's help table of contents as I write this.) Just to get something on the table to work with, it might be something like this:

Introduction

Importing Photos
Import from your local hard disk
Import from your camera
See the photos from your last import

Organization
Create an event
Group photos by keyword (i.e. tags)
Remove a photo from your library (i.e. trash)

Viewing & Editing Photos
Viewing a photo
Rotate a photo
Crop a photo
Enhance a photo's colors and contrast

Sharing
Export photos to your hard disk
Share photos on Flickr
Share photos on Facebook
Share Photos on PicasaWeb
Print a photo

That's a start, but not comprehensive. I suggest fleshing this out as an outline and posting it to this ticket.

[dave]

Thanks for the guidance. Regarding presenting the current content as a user guide and leaving Mallard as a reference, it makes perfect sense. I tried to convey that earlier but may have failed.

I'll try and get some work done on an outline and see what happens.

[robert.ancell]

I took the documentation on the website and put it into Mallard format:
$ bzr clone lp:~robert-ancell/+junk/shotwell-help
$ yelp shotwell-help

(I didn't notice this bug was already progressed. David, feel free to use this rough draft or throw it away!)

[dave]

It seems like you've done a significant amount of work here. It would be a shame to just throw it away! Perhaps I can add pictures and the like where necessary as you noted in your message to the list or make some other small changes.

You've covered most (if not all) of the information I thought to cover and that I had written. I wouldn't add much else. It did seem a bit lengthy in some areas, in my opinion, so maybe it can be condensed.

I believe the license on the web docs would allow us to use it in Mallard. At least there was talk of it here earlier, so I assume so.

[jim]

I think Robert's work is a good start.  To be clear, we certainly have no problem using the text in the User's Guide to fill out the Mallard documentation.

I agree with David, I don't think we need to throw anything away, but build upon this.  Here's some things that pop out at me:

* Screenshots would certainly be nice, especially in the editing pages.  I'd love it if we could get our icon in the top left corner.

* Looking at the Empathy help, most of the subjects are action (rather than topic) oriented, i.e. "Add a new account" and "Change your status".  I think we want to shoot for that in ours as well; "Working with events" and "Rate your photos", etc.

* I'd like it if we fleshed out the Further Reading section on each page.  For example, "Importing from Files" could list "Import from Camera" under Further Reading.

* In the help text itself, simpler is better.  Since Mallard is topic-based help, I feel the pages should be more like a cookbook, i.e. for red-eye:

To eliminate red-eye in a photo:

1. Double-click the photo you wish to edit.
2. Click the Red-Eye button.
3. Drag the circle over the affected pupil.
4. Adjust its size with the slider control so its approximately the side of the redness.
5. Press Apply.
6. Repeat for each affected pupil.

Again, I'm modelling this on how the Empathy help is laid out.  Also note that warning notes in Empathy are set off in their own section with an Information icon beside it.  (See "Add a new account".)

I think this is a fine start.  Hopefully we can keep the momentum going on this, I would love to see Shotwell ship with a real help system.

[robert.ancell]

Please go ahead and make changes, I haven't changed the text much. Is there a better place to commit this document? Jim - would you like a patch against the Shotwell repository and provide patches against it?

[jim]

Robert,

We're going to let Peter work a little more on the documentation before we include it in the trunk. Thanks for your offer, however.

-- Jim

[jim]

I've committed the first cut of Peter's Mallard documentation.  If you run Shotwell from the build directory, it will look for the help files in the help/ directory.  Otherwise, it will use the system-installed help files.

Not yet closing because there's more work to be done.  From here on, we should be working out of our Subversion repository.

Thanks everyone!

[adam]

I've committed Mallard documentation which should be adequate for 0.7.  There's more work to be done to unify it with the user manual on our wiki, but I'll file a separate ticket for that.

[adam]

Also, many thanks to Robert and Peter for all their help getting this documentation started!