Thursday, November 28, 2013

Wabi-Sabi - This way lies madness!

This post is yet another rant about the quality of the technical writing I have been seeing lately. In a LinkedIn discussion-forum about technical writing, I came across a link to a blog post wherein the author seems to both embrace and exemplify the aesthetic called "wabi-sabi" (a Japanese term that generally means embracing imperfections for their artistic value) for technical writing. Personally, I see that as nothing but an excuse for bad writing. As LinkedIn does not have room in their comment field for a rant of this length, I have posted it here.


Perfection in anything is impossible. However, I believe the Wabi-Sabi aesthetic has no place in technical writing. Wabi-sabi embraces imperfections almost to the point of idolizing them. Wabi-sabi began as a mindset of appreciating the imperfections that come with age and wear but has become an aesthetic of intentionally introducing flaws for artistic effect. While technical writing is "an art" it is not Art (with a capital 'A'). For far too many technical writers - or at least people who like to call themselves technical writers - this wabi-sabi aesthetic seems to have become nothing but an excuse for bad writing. 

This article (and the author's entire blog) is a perfect example. There are so many errors it is almost unreadable. It strikes me as nothing more than "content" generated by the vast internet-content grist mills. I understand that this author is very likely not a native English speaker. However, he has chosen to write in English and to write - of all things - about writing. Therefore, it is reasonable to expect said author to actually learn to use the words, idioms, and grammar of said chosen language. He hasn't even come close.

Thursday, August 1, 2013

A flizba by any other name

Warning: This post is mostly a rant.


I read a lot of technical documentation. Software manuals, mostly. Some programming books. 99% of all these books, posts, and guides are utterly worthless. And half of each document or book in the remaining 1% is fluff that I could do without. Because most of these books "cover" very technical topics, it is hard to describe just how nonsensical most of the writing is, in terms a layperson can understand. So, I decided to write an example based on something everyone is familiar with. What follows is a description of a common household object as it would be described by most software manuals today, with the name changed to confuse the innocent. Grammatical errors are intentional. Let me know if you can figure out what the hell I am talking about.

The Flizba Model Paradigm

  • A flizba is a very important device around the building. A flizba has a handle and can be used to swat flies. A flizba can also be used to remove dirt.
  • A flizba is longer than a typical breadbox but the total volume is less than that of the space inside a breadbox.
  • Flizbas can be made by hand or can be made in factory. Preferably one that does not have a witch flying around in it.
    • Important Note: You should not use a flizba to swat at a witch which may be flying around in a factory.
    • When making a flizba by hand, be sure to wrap the wire very tightly.
  • To get to the flizba, turn the doorknob to the left (unless the door is not a door, in which case use the appropriate method, as desired).

The contents of this post is Copyright © 2013 by Grant Sheridan Robertson.

Wednesday, June 12, 2013

FrameMaker Tables & Anchored Frames

Introduction

For my second post about FrameMaker, I thought I would focus on objects with
what I have termed "text-centric outsides." As I explained in my last post
(about FrameMaker), these are objects whose outsides interact with the object
that contains them in a "text-centric" manner. In other words, you can insert
them at a particular point in a text flow and they move along with the text.
There are only two objects that do this: tables and anchored frames. Now, many
books will talk about inserting other types of objects (what I call "graphic
objects") into text but fail to mention that what really happens is FrameMaker
automatically inserts an appropriately sized anchored frame and then sticks
that graphic object inside the anchored frame. In my opinion, it is better to
understand what is really going on. Once you have a solid understanding of the
fundamentals, it is much easier to build up various combinations of these
objects to achieve the desired effect.

As I mentioned in my last post, I will not be repeating all the basic steps
for inserting tables and anchored frames. I assume you already know those
things from reading the "help file" that comes with FrameMaker or one of the
many books that are available. Instead, I tend to dig a little deeper than most
books bother to explain. I like to experiment around the edges and find the
limits of the software I use. This post is based on that experimentation.

Tuesday, May 7, 2013

Understanding FrameMaker Frames

Most books and manuals about software merely state what each menu item does or which menu items you need use in order to accomplish some specific goal. Interestingly, that goal always seems to be something that can be easily done by pulling down a couple of menus. I almost always find myself wanting more. I want to know why the software behaves as it does. Is there some underlying philosophy or grand design? This post is an attempt to provide a little help in this regard, for people who use Adobe FrameMaker.

Introduction

Due to the rich complexity of how frames and objects can be used within FrameMaker, it is easy to get overwhelmed by all the different combinations. However, after working with FrameMaker, I have discovered a very simple conceptual model for classifying this behavior which, I believe, will make it a lot easier to understand and keep track of how these things work and work together.

I will not pretend to teach you everything you need to know about FrameMaker in one post. Nor will I bore you with yet another detailed repetition of menu items. I will assume you have already read through the user manual and are familiar with the basic operations necessary to create and manipulate frames and other objects on a page. What I attempt to teach in this post is a way of looking at how these things work in the background so that it will be much easier for you to remember what fits within what and why, as well as help you figure out solutions to difficult design problems using a rational plan rather than a lot of trial and error.