Tech writer's spot

UI guidelines for web applications

2010-03-12T15:43:00.005+03:00

I've been looking for an industry standard guide to designing Web interfaces. Here I found a good list of guidelines for designers of user interfaces in various areas (Win, Mac, KDE, Java, AJAX, Flash, etc). Still I found nothing like MSDN guidelines for desktop apps, but intended for Web apps. :-(

What I need is a solid basis for our (upcoming) internal guidelines, that technical writers would use to write and translate texts in web applications. If anyone has ideas, please drop me a line where to look up for this sort of guidelines.

A Guide to Technical Writing (1908)

2009-09-21T17:57:00.004+04:00

I never thought that technical writing could be that old. See A Guide to Technical Writing by T.A. Rickard. This book was published in 1908, that is more than 100 years ago!

UPD: And here comes another artefact from the "good old times", a bibliography on "English for engineers" for the use of engineering students, practicing engineers, and teachers in schools of engineering, to which are appended brief selected lists of technical books for graduates in civil, electrical, mechanical, and chemical engineering. Published in 1916.

Mapping MS Word menu items from 2003 to 2007

2009-08-31T14:55:00.004+04:00

When I migrated from MS Office 2003 to 2007, I read several tutorials to get up to speed with the new interface. But now and then I still had troubles guessing where a certain menu item could be hidden in 2007. I felt much happier when I found this interactive reference that mapped 2003 menu items to those in 2007. I still keep it at hand just in case.

Rates for freelance writers in the U.S.

2009-08-14T11:55:00.003+04:00

Guys from Writing Assistance, Inc are offering a free estimate of hourly market rates for technical writers, instructional designers, copywriters, and designers at the U.S. job market (see the Free Publications column at WAI main page).

As I checked out the figures, I began to wonder whether the average rates are really that high (e.g. $50 to $80 per hour for a software techwriter of about my qualification). If so, what were the actual rates before the recent slump in 2008?

Documanga from Google

2009-05-22T19:48:00.004+04:00

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

2009-05-14T20:49:00.002+04:00

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:

Use short sentences.
Use short first paragraphs.
Use vigorous English.
Be positive, not negative.
Dispose bad writing samples.

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

My new "digital inkpot"

2009-05-07T16:27:00.003+04:00

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!

2009-04-30T19:16:00.006+04:00

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"

2009-03-17T15:49:00.010+03:00

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

2009-03-10T14:01:00.003+03:00

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:

Smart approach to document profiling (DocBook)

2008-12-18T19:37:00.007+03:00

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.

Single-sourcing in action

2008-11-21T14:05:00.004+03:00

These days I dived into writing a set of 2 documents, Quick Start and Full Guide, based on the same DocBook source. This must be a fine opportunity to try out the guidelines suggested in my new book on single-sourcing (see it on my bookshelf).

Well... Being so clear and simple when I read it, this book proved quite a challenge in practice. A big surprise was to realize that my present writing style is not modular enough. It takes me much effort to make all chunks more independent, so they would read natural when assembled in either target document.

Anyway, I'm pretty sure that the result will be worth the effort. Will keep updating this blog with new impressions as I move on.

The rights of the reader

2008-10-03T00:12:00.003+04:00

I liked this short discussion of a humorous poster entitled "The rights of the reader" by Daniel Pennac (he wrote a book with the same name). Indeed, this poster is quite in tune with what user-centered technical writers keep in mind as they write. :-)

Do "late sleepers" really work worse than "early risers"?

2008-10-02T20:15:00.008+04:00

I'm a genuine late sleeper. Since my senior school years (it's ~ 12 years now, wow!) I've been studying / working "shifted hours". Most of this time I've been normally coming to school / university / work by noon. And even in my childhood, can't remember if I ever liked the idea of waking up / going to bed early. My creative powers come to their peak in the evening, while squeezing a fresh idea in the morning is murder.

Meanwhile, I often meet people who -- conciously or not -- judge that one must be an early riser to work truly well. Even in the creative sphere of IT this stereotype is popular. Is there any sane psychological ground for it? Or maybe it's just legacy of those times when people had to wake up early to do all the job during daylight?

Odd but true: I love deadlines!

2008-10-02T13:51:00.004+04:00

Really, deadlines are my best remedy for writer's block. Time pressing is stressful, but it helps a lot to realize priorities, take decisions, and stop muddling with trifles.

Hilarious video from Font Conference

2008-07-29T23:17:00.005+04:00

Ha-ha-ha!.. Can't stop laughing. :-D

Just imagine typing fonts... gather together and hold a conference! All those TNR, Arial Narrow, Futura, Comic Sans, Wingdings et al starring in a short clip. Acting and makeup are superb! Tech writers and all font-concious people will appreciate. :-)

10 mistakes in icon design

2008-07-18T17:03:00.006+04:00

Here goes a handy checklist that helps fight typical mistakes in icon design. The author keeps things simple and gives nice illustrations to support his point. Just what an amateur designer like me would need next time when the need for drawing a simple custom icon arises. :-)

Summary:

Insufficient differentiation between icons.
Too many elements in one icon.
Unnecessary elements.
Lack of unity of style within a set of icons.
Unnecessary perspective and shadows in small icons.
Overly original metaphors.
National or social characteristics not being taken into account.
Images of real interface elements in icons.
Text inside icons.
Outside the pixel framework.

P.S. Thanks to Desh for sharing the link.

Trends in web design

2008-07-16T19:23:00.003+04:00

Today I was surprised to learn that writing about trends in web design is so popular. Just google for something like "web design trend" and you'll get tonns of opinions and design samples!

The topic is not straightforwardly "techwriting", of course. Nonetheless, taking a look at carefully selected galleries boosts both mood and imagination. :-)

Once again about TOCs

2008-07-10T16:09:00.005+04:00

Huh, it feels like my blog needs emergent revival with some fresh posts. ;-)

To start with, here comes yet another (wider) collection of creative and beautiful TOCs. I loved it!

"Nu grammar"

2008-05-15T18:39:00.012+04:00

Sarah Maddox posted a summary of the "new grammar" session led by Jonathan Halls at AODC (Australasian Online Documentation and Content Conference) she attended. Her summary hooked me.

Jonathan's interpretation of "grammar" turned out much broader than I've ever took it: "the principles or rules of an art, science or technique". Hmmm... After reading Sarah's post, I took some time to read Jonathan's AODC handout Do you have time to read this? and many points of his "nu grammar" philosophy became clearer.

I agree with Jonathan that (a) in the recent years, communication patterns have changed dramatically (yes, in Russia too!), and (b) technical communicators must therefore respond to people's new expectations towards communication. Yes, we must, though often it's quite a challenge. It's true that people now emphasize the importance of faster, easier, and this way more efficient communication. At my current workplace, I mostly write documents for internal use, and colleagues sometimes ask me to shorten some written piece because they feel frustrated to read that much text. In Russian, we even have a popular ditty for this kind of complaint: "mnogabukav niasilil" -- literally "manyletters couldn'tmanage". :-)

I also agree that many innovations in the techcomm area can help us "win the fight" for readers' / listeners' / watchers' time. I like the ideas of adjusting content for speed reading, delivering information in quickly accessible formats, using collaborative environments, encouraging interactivity and authorship delegation, favoring more conversational style over "official language", etc.

However, I still feel "digital immigrant" rather than "digital native" when it comes to applying "nu grammar" ideas to strictly grammar issues. For example, now and then I'm asked to review my colleagues' documents and emails. When I follow "classical" English grammar and stick to Chicago Manual's guidelines, people say I make their prose too heavy. They want lighter constructions (though sometimes wrong in terms of "classical" English), and make me break my head over rephrases that would be both "light enough" and "grammatically correct" (not to say about clarity).

I just can't reconcile myself with the idea of writing technical specifications in instant-messaging style -- even if I knew it would boost understanding. My current "freedom limit" here is Richard Lanham's idea to replace "official style" with everyday though grammatically valid "business prose".

The grace and beauty of TOC

2008-05-13T15:51:00.004+04:00

Guys from the Design Observer blog have published a small book, The Next Page: Thirty Tables of Contents. It features Table of Contents (TOC) pages from 30 different publications that range from poetry and fiction to non-fiction prose of all kinds. Meeting so much different TOC styles, designs, and structures gathered in one place was fun. The collection inspired me to pay more attention to TOC design and, as the book's authors promised, I found the examples "engaging, the discrepancies between them even more so."

The book is now available as online slideshow at Design Observer's site. Also, these and 40 more TOC snaps are available on Flickr.

P.S. Thanks to Boris for sharing the link.

No new ideas? Here they come!

2008-05-08T12:31:00.003+04:00

Check out a wonderfully inspiring post -- The Birth of a New Idea -- in Dan Blank's blog. Smile and creativity pepper-up guaranteed! :-)

A new kitty

2008-04-22T13:39:00.004+04:00

The "kitty family" living at my workplace keeps growing. Now they are two:

Words and money

2008-04-21T14:21:00.006+04:00

The two articles, 14 Words That LOSE Money and
200 Words That Make Money, are just fun to read. Also, they give two wordlists that may come in handy when occasionally composing or analyzing some marketing text.

Typical day

2008-04-17T18:19:00.012+04:00

The mystery of who technical writers are and what they do at their workplaces in gradually unveiling. In the last few days I found several posts from writers all over the world describing a typical day at work. Well, although the descriptions are typical, they're by no means similar! See for yourself:

A writer's typical day in the USA.

A writer's typical day in China.

A writer's typical day in the UK.

A writer's typical day in Australia.

For me, it was fun to get an insight of other writer's workdays, to find evidence of how different a writer's day can be, and to see what other writers can fit into just one day.

I'll keep updating the list above as I find more posts on this topic (I'm pretty sure there'll be more). Of course, I'll also consider adding my two-pence to this stream. :-)

Agile tech writers

2008-04-17T12:54:00.004+04:00

Yesterday I bumped into a couple of awesome posts by Sarah Maddox, a writer at Atlassian. She writes about her team of "agile technical writers" (a.k.a. XTW, or "eXtreme Technical Writers) -- that is, writers who collaborate with Agile (or eXtreme) Programmers.

Sarah generously shares the secrets of their "XTW cuisine". In particular, her description of a typical XTW day in the first post is very informative. Needa think of re-using some of their XTW tricks in my non-agile environment...

Hello, world!

2008-04-16T21:43:00.002+04:00

After a year or so of lazy blogging at LiveJournal, I decided to try out blogspot features and services. Hope to find here more ways for self-expression -- and more visitors to read my notes and share their experience.