Documanga from Google

Googlers have come up with an awesome document about the architecture of their open-source web browser, Google Chrome. The book grasped 100% of my attention the very moment I opened the link.

This 38-page document is presented as a comic book drawn by the creator of the classic "Understanding Comics", Scott McCloud. The content is rather technical, but the graphics of real Chrome team members and direct speech in baloons are so catchy that I swallowed all the -- otherwise rather boring -- techie stuff immediately and had perhaps the most pleasant tech-reading this year. What a perfect way to tell a story! Grade A!

Techwriting by Ernest Hemingway

As Brian Clark wrote in his post Ernest Hemingway's Top 5 Tips to Writing Well, Hemingway followed very simple yet efficient writing rules in his prose:

1. Use short sentences.
2. Use short first paragraphs.
3. Use vigorous English.
4. Be positive, not negative.
5. Dispose bad writing samples.

Surprisingly, this is what technical writers are often advised to consider.

My new "digital inkpot"

This morning I got hold of yet another "freaky mouse" as one would call it: Wacom Bamboo A6 digitizer (a.k.a tablet). I've been considering this buy for 1.5 years now, doubting all the way if I'll really use it after my first wow's evaporate. But finally, I got "ready for a tablet". Yeah, I feel a happy hippo today. :-)

Here's what it looks like:

Like with the trackball, it took me some time to get used to the device. I liked the vendor's interactive tutorial: it brought me up to speed with the tablet in less than 30 minutes.

I initially planned to use the tablet for editing graphics, drawing raster / vector schemes, and adding smart hand-written callouts and notes to documents and images. Now I also consider the tablet as another handy alternative to a regular mouse. I liked to scroll / zoom in documents using the tablet's touch-wheel, and speed buttons proved nice to navigate back / forward in web browsers. Anyway, I'll need several weeks to fully test the tablet's usability and understand which tasks it covers best. First of all, I can't wait to try it out with pressure-sensitive image editors. The ability to draw wider / narrower lines by pressing the pen firmer / softer against the tablet impressed me in the tablet's tutorial.

P.S. Mind the round-shaped pen holder that looks very much like a real inkpot. Now I feel a real writer! :-D

It's bike time!

Spring has finally come to Moscow and this week I was happy going to the office by bicycle. We have no regular parking slots for cyclers, so I feel free to fasten my bike right to the fence. There it stands safe under surveillance cameras, being hardly noticeable among the other vehicles. :-)

UPD: I've just learnt about an annual event in the USA and Canada called Bike-to-Work Day. It's held since 1956 on the 3-rd Friday of May. Moreover, this Day is part of a whole Bike-to-Work week!

My new "inverted mouse"

Last week I had a 1-day "test drive" using my colleague's trackball instead of a conventional mouse device. Today this experiment ended up in buying an indentical trackball (Logitech TrackMan Wheel) for daily office use.

This device has a "transitional" mouse-to-trackball design with mouse-like left and right buttons and a scroll wheel in the center, which I eventually found very handy. However, at first the new device confused me resembling a ball mouse inverted inside-out, with a ball directly under my thumb. In a couple of hours though, the trackball felt as natural as my old optical mouse.

I spent the rest of the test-drive day enjoying high cursor speed coupled with high-precision cursor positioning and pleasant tactual sensations. In terms of my everyday tasks, it became much easier to quickly move the cursor across windows on my 2 screens. At the same time, I gained more control in selecting text and graphics. And what's important, my usual strain in the right arm and shoulder were gone because I didn't need to move around the entire device any longer.

Logitech also offers a similar cordless trackball. Perhaps, some users would find it critical to have no "tail" connected to a trackball. For me a cord is not an issue because, as I already said, I do not move a trackball around and it lies still on my desk.

The round-up is that I would recommend trying a trackball for typical techwriting jobs. So far I found no down-sides of using a trackball as compared to a mouse (I'll make an update if I find any flaws).

UPD 1: This (and the similar cordless model) are "pure" trackballs meaning they do not have mouse-like sensors on the bottom. These trackballs lie still on the desk, giving you a fine opportunity to click without the risk of accidentally moving your cursor away.

UPD 2: I've been using my new trackball for 2 weeks now, and I'm still happy with it. After some fine-tuning of speed / acceleration settings the device feels just fine.

UPD 3: If I ever decide to move on with my "freaky mouse" experiments, I'll definitely try a foot mouse!

Firefox Book Sprint

I'm looking forward to Firefox Book Sprint scheduled for March 17-18. The idea is to create Firefox user's manual from zero in 2 days. Many writers will be collaborating in a wiki environment both remotely (as I will) and on-site (the Sprint is held within DocTrain West 2009 in Palm Springs, CA). To join, you'll need to drop a line to Janet Swisher (jmswisher-at-gmail-dot-com) and register in FLOSS Manuals wiki.

See details here:

• http://www.doctrain.com/west/2009/program_detail/firefox_book_sprint/
• http://thecontentwrangler.ning.com/

Smart approach to document profiling (DocBook)

Today I visited a seminar on single-sourcing at Philosoft. We had 2 presentations:

• An overview of MadCap Flare (presented as an alternative to AuthorIT, Help-n-Manual, and in many aspects to FrameMaker).
• A round-up of how single-source documents are created at Philosoft.

The round-up was most valuable.

First, Philosoft writers create genuine single-source documents, where each document is built from content pieces stored in a common database. Unfortunately, they did not quite explain which types of content pieces they have and how they arrived to these types. However, they promised to share this info on their website soon.

Second, I really liked Philosoft's approach to profiling output documents in their DocBook environment. They suggest 3 criteria for profiling:

• Subject for document's subject, e.g. a certain software product, hardware item, or person's role, etc.
• Aspect for document's type, e.g. user's manual, administrator's guide, product reference, etc.
• Profile for subject's or aspect's flavor, e.g. software's version for a certain OS, hardware's model for a certain customer, etc.

These 3 criteria make up a unique combination for each document. The guys say this trinity is quite enough for all profiling needs. Besides, knowing the 3 criteria for each output document makes drafting more focused.

Technically, they use 3 native DocBook attributes to tag conditional elements in a single-source database:

• conformance for the subject
• userlevel for the aspect
• condition for the profile

As for myself, by now I've been maintaining a database with one source XML document for each product's documentation set ("subject" criterion). Where needed, my XML sources are tagged with condition attributes to define the output document's type ("aspect" criterion). For all flavors (e.g. product version) I've been using XML entities ("profile" criterion).

Now I'm thinking of trying the 3-criteria approach and probably fine-splitting my per-product XML sources into pieces to make up a joined database.