I'm on California TimePublished on 2014-10-01
I've recently had some time to work on docs for California, a new calendar application being developed by the Yorba team.
They've just released version 0.2 of California, so I thought I'd jot down a few notes about the the application and the docs.
California, the Calendar
This is only California's third development release, but it already takes care of the modern-day calendaring basics (for example, syncing with CalDAV and Google calendars). To me, though, the best feature of California is how it allows you to enter event details using everyday phrasing.
You can type out your events like this:
- Go to Economics class every Wednesday from 6:00pm to 9:00pm
- Meet James and Aaron for Dinner at 7:00pm @ Ombra
. . . and California will take care of adding the event(s) to your calendar.
The parsers are already reasonably complex, and they keep making them better. There are some event entry tips on the wiki, and I'll be adding more of this information to the help as a separate, detailed topic.
California, the Docs
As for the docs, here are a couple of notes:
- I noticed that Shaun McCance included some Schematron checks in the GNOME User Docs, so I'm including those same checks in the California docs. I'm only checking for proper use of <desc> tags and inclusion of a license file, but I can set up more checks in the future.
- I'm using the Mallard Expanders feature so that the user can choose help that is relevant to them and skip irrelevant information. I like how this approach makes the help easier to digest for readers, particularly for longer topics. Technical writer Tom Johnson talks about some of the pluses and minuses of using this feature towards the end of a [recent blog post](http://idratherbewriting.com/2014/09/22/using-collapsible-sections-to-brin g-tasks-and-concepts-together-dita/), too.
- There are a few areas where task instructions are similar across topics, so I'm using xincludes and xpointer to limit repetition of some common steps. This means a bit less work for translators, and less effort for us to maintain the docs in the future.
- Although it's not a big deal in the gradiose scheme of things, I'm now making an effort to follow the GNOME git commit guidelines. It's not difficult to follow them, and it makes all of our work a bit easier in the long run. I hope you'll review the guidelines and follow them, too.
There's still more to do with these help docs. I'll be adding more help topics as development progresses, but things are off to a good start.