Tuesday, February 8, 2011

Good Manuals Matter

Due to growing dissatisfaction with Lightwave's clumsy GUI and Carrara's utter brokenness, i've been trying out some new 3D graphics tools over the last couple of weeks. In some cases, all i have access to are the developer's on-line documentation. While this allows me to get an idea of what the tool may be like prior to purchase, it's not near useful enough as a trial or demo would be. Still, there's much to learn from documentation... including just how detail oriented the developers AREN'T.

Of particular note is Modo, by Luxology. While at the Carrara & Lightwave forums, i've seen a lot of users pointing to Modo as an alternative to the buggy & less-than-robust offerings from DAZ & NewTek (especially in the case of DAZ's Carrara). Luxology has a link for "Try Modo" at the top of their web page... and it tells you that a trial will be available "at a future date." Hm, not helpful. So i've proceeded to read their online documentation. Sadly, i'm rather unimpressed with a few things. i'd love to rant about the "Shader Tree" concept, but i don't know enough about it yet, so i'll focus on a more subtle issue that people tend to ignore these days: Readability and language use.

While reading Luxology's documentation for Modo, i've discovered that they really need to hire a proofreader. Now, i have a similar complaint with magazines such as Future Publishing's Computer/Future Music magazines, but, in this case, the problems are a bigger issue than simply embarrassing flubs; they're obstructing the learning process. Worse, the clumsy writing suggests to me a developer-wide lack of attention to detail. It's far easier to correct a document than to debug software. So why not do it? It shouldn't be considered a lower priority. Not only does it reflect poorly on the company as a whole, it makes the product more inaccessible.

Take a read of this page, for example: http://docs.luxology.com/modo/501/help/pages/modotoolbox/modoMindset.html
  • Run-on sentences
  • Sentence fragments
  • Missing commas
  • Possessives (apostrophes in possessives are almost entirely missing)
  • Complex sentences where multiple simple sentences would be better
  • Various other typographical errors
  • Lack of breaking procedural content into steps or bulleted lists
The documentation doesn't read as though the cause is a non-native English speaker. While i think that case is no excuse, it's at least an explanation & the solution is to hire a native English speaking proofreader. Even with a native-English speaker (or native-[insert documentation language here] speaker), you still have to take care. There are plenty of native-English speakers who have horrendous language skills, and that just will not do for imparting information in an efficient and effective manner.

It seems that in today's "do more with less" market mentality, it is assumed a proofreader isn't necessary so long as "spell check" is used. The problem with that attitude is that none of the above bulleted items can be caught with spell checkers. At best, a grammar checker might provide some feedback, but (from my own personal experience using MS Word) they're still a far cry from the abilities of a human being who's native language is that used by the documentation (MS Word's grammar checker also tends to flag a lot of non-problem areas as well).

Worse, it also seems that a dedicated technical writer is also considered "a luxury item" that companies would rather do without. When i read documentation like this, i can almost visualize one of the programmers being told to sit down and explain how the software works. Some people may think that this is ideal; who else knows the product better than the programmers? The problem is one of specialization. Programmers tend to be great at code and even work-flows, but not so great with communication & language (sometimes they're utterly horrible at it). Why make the developers write the documentation when their time is better spent writing (and debugging) code? Put a dedicated technical writer on the team. Someone who's specialty is the conveyance of information to a wider audience (wider than just "the people building the tool").

Clarity in technical writing is essential to the goal: conveying information to the reader. For that reason, i might even argue that readability is even more important for documentation than most other forms of writing.

Most disconcerting of all: if this is the state of their attention to detail in their documentation... what might i infer about the attention to detail in the software design and coding? Looking at postings on the forum, it sounds as though the release of Modo 501 was premature (at best; at worst it's just damned sloppy). Modo 501 is apparently the first Modo release to be 64-bit on the Macintosh. As witnessed with other 64-bit "first versions" of other math-heavy products, there are a lot of "shouldn't be" problems in the commercial release reported by users at the forums.

Maybe this is why Luxology doesn't actually offer a trial version for download, currently; it would give them a black eye in PR. Still, they're selling the product... Not very encouraging.

No comments:

Post a Comment