Jabberwock 2: the solution
In our last post we saw that technical writers need to make sense out of material that often is beyond their understanding and for which they do not have the requisite academic background to fully understand. On the other hand, experienced writers also know that they have a real job to do - and that their job entails more than just making a few cosmetic changes. They know that technical communication must ultimately serve the reader - there must be something that the writer can do to clarify the information and make reading part of the process that makes the product usable.
What then, can we do? Good writers will begin by following Alice’s strategy:
“Somehow it seems to fill my head with ideas- only I don’t exactly know what they are! However, somebody killed something: that’s clear, at any rate-”
Here Alice is using the logician’s trick of stripping away the surface semantics and looking at the basic syntax - “somebody killed something” - that’s at least some kind of beginning. And this is what experienced technical writers actually learn to do - begin sorting out who does what, what causes what, what relationships do the parts have to each other - even if the full nature of that relationship is not yet understood.
OK, so fine - the writer understands what is going on - but what about the reader? Even before technical communicators understand the subject matter, they must first try make the material “sound logical” - just by the way the words and sentences are strung together.
And so, we can take our Naming Conventions piece from the last Post and rewrite like this:
Naming and Referencing Conventions
In Chapter ? you learned about the difference between Box and Arrow elements. There are also differences in the way you name and reference these elements as discussed below.
How Arrow Elements are Referenced
The main convention to follow when referencing Arrow elements, is to assign them labels. As opposed to a “name”, a “label” enables you to ? (need more info here on the difference between a name and a label). The following figure shows a box and arrow elements, with the arrow elements labeled:
pic of labeled arrow elements here
How to Name Box Elements
Unlike Arrow elements, Box elements can have actual names. This means that when you assign a name to Box element (what happens - need more info here). Here are the conventions for naming Box elements:
- Names for box elements are optional.
- Names can be assigned to any Box element: states, data-stores, and modules.
- When to assign a name to a box element: you should assign a name to a Box element if the element is referenced in an expression and its name is important for the clarity of the specification.
- Box elements can have the same names. However, you must distinguish Box elements with the same name from one another by preceding their names with their ancestors’ names until their hierarchical path is unique. For example, the following figure shows two Box elements with the same names, with different hierarchical paths:
pic of this here
What Have We Done?
What did we do to improve this piece? Briefly, we’ve applied as many stylistic improvements as possible:
- Rewrote passive into active voice
- Turned negative expressions such as “non-unique” etc. into “positive” expressions.
- Organized the material using expressive titles - this is one of the easiest, and at the same time, one of the most effective things to do.
- Indicated where we need more information.
- Indicated where we need examples and illustrations.
- Rewrote the material to unfold in a logical, progressive manner so that the reader can follow the ideas and can see their significance.
We haven’t been able to finish the piece because we still need to gather more information. But we’ve been able to apply an impressive number of well known techniques from any experienced technical writer’s arsenal and we’ve come a lot closer to finishing the job - now we just need to gather a few more facts and everything falls into place.
Finally, Don’t Be Afraid to Interview and Get the Facts
Although Alice has heard the Jabberwocky poem first and formulated some kind of basic, overall understanding, she doesn’t leave it at that. Like a good technical writer, she eventually tracks down someone who can explain the technical terms and help her fill in the blanks - this may cause her to revise her original understanding of the piece - it will certainly help her to explain the piece to her anxious readers:
“You seem very clever at explaining words, Sir,” said Alice. “Would you kindly tell me the meaning of the poem called ‘Jabberwocky’?”
“Let’s hear it,” said Humpty Dumpty. “I can explain all the poems that ever were invented- and a good many that haven’t been invented just yet.”
This sounded very hopeful, so Alice repeated the first verse:- -
“‘Twas brillig, and the slithy toves
Did gyre and gimble in the wabe:
All mimsy were the borogoves,
And the mome raths outgrabe.” -
“That’s enough to begin with,” Humpty Dumpty interrupted: “there are plenty of hard words there. ‘Brillig’ means four o’clock in the afternoon- the time when you begin broiling things for dinner.”
“That’ll do very well,” said Alice: “and ’slithy’?”
“Well, ’slithy’ means ‘lithe and slimy.’ ‘Lithe’ is the same as ‘active.’ You see it’s like a portmanteau- there are two meanings packed up into one word.”
“I see it now,” Alice remarked thoughtfully: “and what are ‘toves’?”
“Well, ‘toves’ are something like badgers- they’re something like lizards- and they’re something like corkscrews.”
“They must be very curious-looking creatures.”
“They are that,” said Humpty Dumpty: “also they make their nests under sun-dials- also they live on cheese.”
“And what’s to ‘gyre’ and to ‘gimble’?”
“To ‘gyre’ is to go round and round like a gyroscope. To ‘gimble’ is to make holes like a gimlet.”
“And ‘the wabe’ is the grass-plot round a sundial, I suppose” said Alice, surprised at her own ingenuity.
“Of course it is. It’s called ‘wabe’ you know, because it goes a long way before it, and a long way behind it-”
“And a long way beyond it on each side,” Alice added.
“Exactly so. Well then, ‘mimsy’ is ‘flimsy and miserable’ (there’s another portmanteau for you). And a ‘borogove is a thin shabby-looking bird with its feathers sticking out all round- something like a live mop.”
“And then ‘mome raths’?” said Alice. “I’m afraid I’m giving you a great deal of trouble.”
“Well, a ‘rath’ is a sort of green pig: but ‘mome’ I’m not certain about. I think it’s short for ‘from home’- meaning that they’d lost their way, you know.”
“And what does ‘outgrabe’ mean?”
“Well, ‘outgribing’ is something between bellowing and whistling, with a kind of sneeze in the middle: however, you’ll hear it done, maybe- down in the wood yonder- and, when you’ve once heard it, you’ll be quite content. Who’s been repeating all that hard stuff to you?”
“I read it in a book” said Alice.
As technical writers, let’s hope we have the opportunity to have as sympathetic an SME (Subject Matter Expert) as Humpty Dumpty - he may be a little vain, but at least he’ll answer the questions, and he even admits when he doesn’t know. Can we hope for anything better?