Documentation and Change

Here's an issue that many of us run into (I'd like to think). What happens when you want to change something in your documentation that's not necessarily broken? What’s the best way to handle mere upgrades and nonessential documentation improvements?

I ask this b/c many writers and editors are loath to make changes if something isn't necessarily broken. If a fact is misrepresented or wrong, it's generally not a problem to fix it. But if our evolving experiences can identify a product improvement, it's often a tough sell to make the change.

Things like boilerplate text, layout, formatting, descriptions, and logical flow of a document are all fair game for improvement. I don't claim to get things right the first time. I don't think it's reasonable to expect everyone to get things right initially. It's only after a waiting period and a sufficient amount of reflection that someone can claim to have nailed down the BEST way of doing something; progress is iterative. I believe that journeymen technical writers have a much higher hit rate of near perfection the first time, and I'm approaching that point - but not yet.

The resistance to make changes I believe comes from the fear that you will confuse and disorient the user. This is a fair critique. A second resistance to change is the extra work that comes along with implementing the change - and the need to implement the change everywhere and at once. A lot of work is involved with a proper system-wide change. Third, a change that works somewhere might break something in a remote part of the system. You're really taking a risk by making changes in a system that already is functional. Fourth, you set a bad example and expectation that nothing is set in stone, and anything can be changed at any moment which might lose your reader's trust.

Please reply and add your thoughts on why non-necessary change should be avoided in technical documentation.

I'm planning a follow-up to refute this in a later post, so save your change is good! replies for then.

steel cage job title championship match

Two disclaimers:

1. I acknowledge that these titles are arbitrary.
2. The distinction I describe is my own and my thoughts probably represent the minority.

Less so in recent years because I've had steady, happy employment, but I often agonize over the definitions of technical writer vis-à-vis applying to job postings. Documentation Specialist is probably the second most common job title (which I held in two government positions) which every TW-type job applicant searches. So when one is bored, fretting, and unemployed, trying to sort out the difference between the two is happily time-consuming. I'll add that the HR people who submit job postings probably don't give the difference a second though. But you know, we're writers - so we obsess over definitions.

I don't know if this was the purpose of the blog entry or not, but Collin Turner's discussion of a subject matter expert (SME) has helped me make a sharp distinction between technical writer and documentation specialist.

SME is a term that's thrown around loosely (at least in my experience), but Turner starts with a salient point in that an SME "provides needed content." The SME is the source of the content. The documentation specialist then chaperones the content through the documentation process until a product is published.

In my limited world view, I'll suggest the following difference: While neither the technical writer nor documentation specialist creates the product (computer application, piece of hardware, or process) that must be documented, the technical writer creates and is ultimate responsibility for the content supporting the product. He or she performs the requisite research inside and outside of an organization to identify, collect, and organize this content.

Collin Turner's description acknowledges these internal conflicts, but lays the organizational knowledge arbitration at the SME's feet.

When I am wearing my technical writer hat (which I like to wear most of the time), I am navigating my organization and available resources to identify and collect all the required content. This means obtaining different functional organizations' ideas of a product, resolving their differences, and presenting a unified view.** Secondarily, I need to have confidence that I can identify with the target audience in order to create effective documentation from the raw data which I've gleaned. This is a real world description, not some idealistic cut and paste from engineering and marketing documents, fix the grammar and save as perfect documentation dream.

I generally feel that a good technical writer must become competent enough in the subject he or she is writing about to answer most questions about it. In the SME-documentation specialist system, the DS has a place to ask questions, but isn't ultimately responsible for the content.

The biggest problem that I see is when an SME doesn't have a vested interest in the user and doesn't take the time to understand the user's documentation and learning needs. When the SME is an engineer or scientist, he or she is too busy creating the widget. But this system succeeds when the SME is in marketing and understands that his or her success or failure depends on the customer's success or failure.

**Any good TW knows that his or her understanding of cross-departmental viewpoints somehow is really valuable to the organization. If anyone in upper management realized this too, I think that TW's organizational roles could be elevated.

If I knew then what I know now...

This is 1/10th a test if trackbacks work, but mostly a comment...

Tom asks the age old question, would you keep doing what you're doing, or do something else. Well I sort of intended to be a tech writer from college...

So the funny thing is I don't specifically enjoy writing, but I'm good at it. I realized this in college as an engineering major. Because in those days, putting in hours of required studying wasn't my strong suit, but my passion for techie stuff was, I put these two things (engineering + writing) together and got a writing oriented degree, with the intent of using it in the technology field.

Do most people go into their college studies all idealistic and truly want their career to orient itself around their decided major? I don't know - but I did. Would I like to be a full time engineer now? Heh, I don't know about full time, but it's fun to put down your pencil and pick up a development environment application.

I've flirted with the idea of other vocations: law (but I don't want to deal with lawyers), teaching (but I like working alone), ISD (same as teaching). These are all in the create or communicate sphere, so I don't know if I'm going so far out on a limb as an oceanographer. OH yeah - I'd like to be a green contractor, but that community is so old-boy network around here, the thought of it turns me off.

Would I mind being a TW in 20 years, writing manuals? Maybe not! It's hard to say, but as long as the technology I write about is engaging, there's a good possibility I will be.

extra wide

What kind of display do you have at work and at home? I find these ergonomics fascinating, since your monitor is akin on the wheels on your car or your stereo's speakers; it's the main interface between the machine and what the machine works against.

At home I share 1 13" laptop. The screen a little bit small but fine for its intended purpose. I will say that if you're in the market for a laptop that you will use for more than Office-type or web browsing applications, splurge and get it with a screen that has a decent off-axis viewing angle. We watch a lot of DVDs on the laptop, and it's narrow viewing angle is limiting.

At home I also have a beautiful 21" trinitron CRT display for my desktops. What more can I say, this is what I was pining over 10 years ago. Accurate, bright colors, with detailed resolution. Plus it doesn't have to deal with the ClearView-type font dithering that most LCDs are sensitive to. The only downside is that it sucks about 120 watts of power and is HUGE.

Finally, my work displays. I started with a 19" Viewsonic CRT - Fabulous monitor. Then moved to a 17" LCD, this was a step backwards because of the reduced resolution, and as I recall, going from a curved screen to a flat screen was a little funky on my eyes for the first few days. I also remember that the LCD screen was too bright. This made it a little bit difficult working in a dim environment because the screen was blaring in your face. Next came an upgrade to a 19" LCD. Now we hit the sweet spot! The 19" had a fine amount of resolution (2 documents side by side in Frame), good color accuracy, and showed precise text once I got the hang of Clearview. I was happy.

But wait - so then the paradigm shifts when I got a 24" HUUUGE wide screen LCD display at work. At first I was blown away - our home TV is 19", and this screen feels much larger than my 21" CRT. I'm going to make this long story short:
For the way I work, a widescreen is overkill. I work very linearly, I don't need to see or refer to 5-10 different pieces of information at once. I generally write a document straight through, edit images one at a time. There are few dynamic dependencies. I'll contrast this with when I was coding or designing websites, where you need to refer to several windows of information at once.

The split screen feature in MS word is great for viewing two parts of a document simultaneously, but that's the most I've ever needed. Now I can have 2 frame documents side by side, but at almost 100% for each. This is nice, but unnecessary. Further, there's the potential to have too much visual information, such that it can be distracting.

Do any other TWs out there use wide screen or multiple monitor set ups effectively, for the TWing part of their job? I can see for content management or designing a help system, it could be useful, but for the straight task of writing and editing text, I'm completely unconvinced.

long time

It's been about a year and a half since I've posted here, and the world of tech writing blogs has not grown too much bigger. I still lament that most tech-writing discussion centers on the tools of the trade, rather than the craft of the trade. But maybe this time around I'll have something interesting to chat about.