Previous Entry Share Next Entry
DevDocs/Tools Hackfest day one; Handling lots of screenshots
DevDocs/Tools Hackfest day one

You find me, Phil "Sensible" Bull, seeking refuge from an uncharacteristic early-December British snow-apocalypse, in the warmer, sunnier climes of Berlin. It's -11 degrees C out there. My legs went numb for a while. But there's zebra steak (courtesy Openismus) and Internet (courtesy Openismus), so I'm happy (courtesy Openismus).

Today we spent a lot of time discussing the GNOME developer platform and "developer stories" (essentially, who is trying to do what with GNOME). It looks like a decent platform overview is a must-have, so we worked on stubbing one out, and discussing the roles of the various libraries and what they offer to developers. We have a really impressive platform, organised in a really confusing way.

A big project over the course of the hackfest will be the writing of a number of awesome* ten-minute introductions to various GNOME technologies. The plan is to have a handful of tutorials for writing interesting apps using Clutter, Telepathy, GStreamer and so on, which you can work through over a lunch break and which leave you enamoured with GNOME. It's pretty amazing what you can cobble together in about an hour - Johannes has made some sort of noise weapon, for example.

One particularly nice thing that popped out of the discussion was the identification of K-12 (school) kids as an interested developer user group. We have people out there using open-source tools to teach programming and we could be doing more to support them. Any ideas, folks?

(* Technical term)

Handling lots of screenshots?

If you're dealing with a lot of screenshots in your documentation, you might be interested in one of these tools:
  • Tuxtorial is a tool for producing image-based walkthrough tutorials. You can host your tutorials on their website.
  • QuickShot is an almost-automatic screenshot capture program, and supports translations.
Some types of documentation are well-suited to a heavily-visual approach (like walkthroughs), but not all of them. We tend to use screenshots sparingly in the GNOME and Ubuntu docs - overusing them distracts from the textual content, and they lose their power to highlight key points and illustrate things that are difficult to describe. That said, there are a few places where we should be making better use of them, but we haven't been because of the translation burden.

  • 1

Don't forget Video Tutorial

I found that 10-30 minutes video tutorials are much better ways to introducing concepts and over viewing topics. It's specially powerful to impatient people to dive in and start to grasp the concepts.

Since now a date, web video no longer depends on the Flash plug-in, I hope you will not only use more videos to demo visual effects, but also can use more videos on introducing tutorials.

Re: Don't forget Video Tutorial

IMO "10-30 minutes" and "impatient people" does not fit together :-) and I hate projects which want me to invest 10 minutes for watching a video where I don't know beforehand if it answers my questions. I really like having a text which I can skim, looking for a project summary, an introduction into concepts, and code examples. Esp. for the last point it only takes 5 seconds to see whether the text provides code. In contrast, skimming a 10-minute video is nearly impossible (but then again, videos nearly never provide code samples in useful form).

Make sure you take a look at Shutter.

  • 1

Log in