May 25, 2007

Split over Splits

At NI we have a company-wide style guide. One of the weirdest things about it, and something which I've had the most trouble getting used to, is the guideline against splitting verbs.

Before I came to NI, I'd write a sentence like this:

You can also double-click the Add function.

But now I write like this:

You also can double-click the Add function.


You must manually specify the value.


You must specify the value manually.

See the differences? I had no idea that people wrote things like "also can" until I started at NI. And I disagree with the way it sounds and looks. (At least, for the first example. I can understand the way we rewrite the second one.) But since then I've noticed many other publications, such as the ESPN Magazine, do the same thing. I guess my brain had skipped over this construction before, but now that I actually have to write this way, I notice it more.

When I had the chance to write the documentation for MATRIXx 8.0, I decided against using this guideline. I just think it looks/sounds weird. But when I switched back to LabVIEW-based products, I had to ease back into using this construction again. Every time I start writing "can also," it's like I have to flip my brain around. I'm getting used to it again. I still think it looks weird and don't like using it. But now that I've seen other places use it, maybe I don't mind it so much.

I know some people don't care about verb-splitting, but others really enforce the "rule" against it. Our company-wide style guide is a communal effort that involves input from all the technical writing product groups. At least one time that I know of, we've voted to remove the restriction on splitting verbs. But even though the company style guide might say this, the product-specific style guide (which is our first point of reference) might disagree. Even if that isn't the case, your manager who reviews your content might not want the verbs split.

Anyway, just some random commentary on something that I find odd :-)

May 16, 2007

The LabVIEW Documentation that Anyone Can Edit

I don't know how I missed this, and I apologize for not posting it sooner! For those of you who are familiar with wikis, the LAVA (LabVIEW Advanced Virtual Architects) group has a wiki for LabVIEW. I encourage you all to go and contribute your knowledge to this compendium. Communication among customers about LabVIEW always is a good thing. It will be interesting to see how this wiki compares to and/or augments the documentation produced just around the corner from me at NI :-)

It's an interesting idea for official NI documentation, too. For example, see the MSDN wiki that I posted about a year ago. It's good to see this kind of thing spring up organically among customers.

May 11, 2007

Improving the Readability of Text Online

A company called Walker Reading Technologies has produced research showing that the human brain is not "wired" to read text in the traditional way we print it, which is in blocks. In short, we're constantly filtering out text that surrounds what we're trying to actually read. This filtering impedes our comprehension of the material.

Supposedly, the optimal format is a series of "short, cascading phrases" that look really odd but are easier for the human brain to comprehend. Of course, Walker Research makes a product that reformats text in this manner automatically :-) Apparently the company has improved some test scores by simply putting tests in this new format. A major textbook publisher also has contracted Walker Research for help with online textbooks.

I'm skeptical about company-conducted research that conveniently provides an excuse for purchasing a product from the same company. But the theory is still interesting. NI does a lot of documentation "online," meaning shipped as HTML. And the very essence of our jobs depends on readers comprehending the material. Maybe this new theory means we'll someday

be writing documentation

like this?

Edit: A link to the ensuing Slashdot discussion.