mythteller | Entries tagged with techwriting

I sent a document out last week for review. It's a real bitch of a document to write because most of the screens in this web-based are simple fields to fill in. The problem is that most people don't know what the fields mean or how they work with the rest of the application. To be fair, we inheirited this application from another company, but this doesn't make my job any easier.

This is the email conversation I get from one of the programmers after I send out the reminder that his comments are due today. I have changed the comments to protect the company secrets and promote hilarity.

Programmer:
See below some of my comments:

Window 10 - The value of the frufru object should be daffodils.
Window 13 - When tracking the data, make sure you wear a purple party hat.
Window 16 - We don't support that feature anymore. We're way too cool for that.
[snip]

Writer:
What do you mean by "Window #" in your references below?
In future reviews, I would prefer that you add your comments directly to the PDF and publish your comments.

Programmer:
Is the number displayed under Window menu, I think is the slide number.
You have a total of 58.

*I open the PDF and look below the Windows menu*

Writer:
That's the page number. This is a book with 58 pages.

===============

After reviewing my 58 page document for a week, he only had 7 comments. This either means I'm a genius or he didn't read it until this morning. As much as I'd like to believe the genius idea, I might need to have a wee chat with his boss.

So I'm working on a document for a product that has an import and export feature. The feature is pretty straightforward, but being a conscientious technical writer, I want to include context is when and why a user would want to import or export the data in this application. Just so you know, the sections are called Importing Data and Exporting Data as an SQL File.

I write to the coders (who are in France) and ask them for examples on when and why a user would perform these tasks. Here's what I get:

France coder: Write this for each section:

Importing Data: This process explains how to import data. You only do this for a special occasion.

Exporting Data as an SQL File: This section explains how to export the data as an SQL file. You only do this for a special occasion.

And I'm thinking What part of the title doesn't tell you all that already?!?! This just reminds me of what coders really think of the technical writers: when we're too stupid to really understand the technology, so we just parrot the obvious so that the lawyers can say we covered our asses.

So I write back and ask what is this Special Occasion would be ("I can't just put "special occasion" as when to perform these tasks. I need a reason!"). He writes back:

France coder (this is copy/pasted from his email): I have no idea. I personally have no example but from my experience in SW support I know it may be usefull one day.

After asking a few more probing questions, I finally came up with something to give the user some context for these features, but I got mostly blank stares from everybody. I think I'm going to suggest to the marketing team that include a complementary mirror and smoke machine to make those special occasions more dramatic.

Pay no attention to the man behind the curtain! He may be importing or exporting data, but no one know why!

WHIIIZZZZ BANG!

So I'm working on a document that was written by some technical guys in France. That's right: French engineers tried to write a User Guide in English and it's been given to me to edit and rewrite by the end of this month.

Did I mention I'm only working two days a week nowadays? That means I have 5 days left to work on this project (unless they give me more billable hours).

I'm going through this document and it's very badly done. Aside from the grammar and spelling mistakes, they seem to think that explaining a task involves taking a screen grab of the application, pasting it in Word, and writing "You use this screen to do ABC." They're leaving it to you to figure out exactly how to use the screen to perform said ABC task.

After all, if you're not smart enough to figure out how to perform the task on your own, you shouldn't be using this application (this was said to me once by a project manager who was complaining that the tech docs were too long).

Consequently, every section of this Word document has 50 words of text and three screengrabs each, but no real procedures written out. Which means I'll have to somehow divine the procedures myself and write them out.

I showed this to my boss, pointing out all the cryptic screen grabs that do nothing in the way of actually explaining how to perform the tasks that the application was designed to do. He grinned and chortled "You know what they say: a picture is worth a thousand words!"

"That's great," I replied. "When you take a picture of a sunset, every person who looks at it can come up with their own 1000 words and all of those words will be right. In technical writing, you need to make sure that every reader who looks at a picture comes up with the same 1000 words."

Which means I'll need to retake every screen grab and make sure it is relevant to the procedures I will have to rewrite anyways. Oy.

If you're ever thinking about going into technical writing, just remember that no one will care about writing excellent documentation as much as you do. The sooner you realize this, the happier (or at least less frustrated) you'll be.

I'm working on a new project to covert and edit some documents from Word to Frame. I analyzed the documents that were submitted, estimated the time, created a proposal, had it approved, and got to work.

When I finished converting ABC.book to Frame, I started editing it. Then my client gives me a new version of the document. I grumble "Is this the final version?" My client says it is, so I figure it has some minor changes to it. I finish my edit with the intention that I will compare the two versions and simply add what was changed to the new document.

I just looked at the new version of this document. It's not a NEW version as opposed to a COMPLETELY DIFFERENT version. Nothing in it is the same -- they are completely independent in every way possible. Okay... they have some similarities: they are both badly written.

What's worse, this new document (DEF.book) is twice the size of the ABC.book! It's like you give me a week to read Moby Dick and prepare a book summary, only to switch it on the last day with A Tale of Two Cities and say "You'll still have that report ready by tomorrow right?" I can, but it'll start off with the line "It was the best of whales, it was the worst of whales..."

So I go see my contact, explaining that I cannot deliver this today. He's incredulous. "But I promised the client I would deliver it today. Okay... just don't do a deep edit. Can you get it to me tomorrow?"

I wasn't supposed to come in tomorrow. I was supposed to only work today. *le sigh* He'd better hope I have no questions to be answered on this new document or he won't be getting it tomorrow either.

*grumble*

Current Mood: angry

Dear Previous Writer,

Company acquisitions can be a bitch. I have now inherited all the documentation from the two companies that got absorbed by my current client and I need to reformat, restructure, and in some parts, rewrite it so that it meets my current client's branding and style standards (ie: my standards).

So as I navigate through all these documents, I'm noticing that you've at least been very consistent in your misunderstanding of technical documentation design and layout styles. Since I am now having to wade knee-deep in this morass with the goal of cleaning this pool out, I would like to point out a few things:

Paragraphs that are flagged with NOTE and CAUTION are supposed to be used sparingly, which increases the probability that the reader will read them. If you use NOTE and CAUTION every 5th or 7th paragraph, the reader will stop caring.
Bolding 80% of the text will not make that text stand out. In fact, it will have the opposite effect, making the non-bolded text seem more prominent.
What is your obession with tables?!? Pages and pages of tables doesn't help anyone find what they are looking for!
The number of pages in a proper Index should be 10% of the total number of pages in the book. A five page index for a 500 page User Guide is not thorough enough.
Use your paragraph styles consistently! No manual formatting! If you need to change something that affects the whole book, updating your styles takes way less time than manual reformatting.
If you include a screen grab, don't make it so small that I would need a microscope to read it. Crop the screen sample so that I can make out what you're trying to show me (callouts are helpful).
Articles, pronouns, and properly applied punctuation are our friends.

That's enough for now. I'll add to this list as transgressions arise. In the meantime, I'm trying out this wee Frame application is supposed to help me strip out unused styles from the docs.

Gah. The things I do for money.

S	M	T	W	T	F	S
			1	2	3	4
5	6	7	8	9	10	11
12	13	14	15	16	17	18
19	20	21	22	23	24	25
26	27	28	29	30	31

Whispers from the Myth Teller

Facts are a poor substitute for good truth telling.

Entries tagged with techwriting

The End of Books is Nigh

The Mystery of the Special Occasion

Words vs Pictures

Nobody understands what I do here

Documentation Formatting Hell

Profile

January 2025

Syndicate

Most Popular Tags

Page Summary

Style Credit

Expand Cut Tags