Learning from Poor Writing

A wise person learns from others' mistakes. Any competent Business Analyst must master written communications. This flog post (flog + blog) presents lessons from unprofessional writing. I try not to pick on common people (e.g., Facebook posters). Instead, I focus on those who ought to know better: mainly, reporters and the news organizations that are too miserly to hire copy editors.

Bent-piped Gaffs

Reporters often accept news releases from companies or government agencies and then post them with minimal editing. That's probably what happened with this story. The text went in one end of the pipe and came out the other end, uncorrected. The quality doesn't speak well of the News Director who posted it under his name. He may be a great reporter or manager, but his proofreading is substandard, even by the news industry's rapidly deteriorating standards.

The USFS manager who probably provided the source text sits on the borderline of forgiveness. Managers reach their position because they can do one or two things well. One of two halo effects result. (a) Since they do something well, they think they can do all things well.  (b) Since they do something well, their managers expect them to do all things well (including writing) and withhold budget for hiring professional tech writers. Both situations can result in unprofessional writing. Most of the time, poor writing does not matter, but when the subject impacts profitability or safety, poor writing can cost jobs or even lives.

• In the opening sentence, using the verb to be equates the fire with the area. That is a logical error. The fire covers 3,791 acres or has burned 3,791 acres, but we shouldn't say the fire is 3,791 acres.
• You don't need to be a firefighter to know the difference between a [Name] Complex Fire and a fire complex. A wildfire complex forms when two or more fires merge. Complex may also be loosely applied to multiple wildfires close enough together to be treated as a single fire. 
• In this case, two fires have merged, but the third remains separate, across the valley. Therefore, the Summit Complex Fire ought to be called Summit Complex Fires. 
• The complex fire should simply be The complex. The complex of fires would be acceptable but wordy. 
• Containment is not something you place on a fire. You don't have 9% containment on the fire, you have 9% containment of the fire. A better headline would state, Summit Complex Fires Containment at 9%.
• 9% is a measurement. You don't spell out measurements.
• Nine-percent should not be hyphenated. The focus of the sentence is on 9% (e.g., the containment has reached 9%). When the unit of measurement might otherwise require pluralizing, we hyphenate the number and the unit of measurement, and we keep the unit in the singular.
• Example: The six-foot statue (not the six feet statue) 
• Percent does not require pluralizing. For example, we would never say, nine percents.
• In lightning caused incidents and heat related illness, the author commits the opposite error by failing to hyphenate. Where a pair of words form Correct: lightning-caused incidents and heat-related illness.
• (Sarcasm Alert) I just love "The fire activity of the McCormick Fire has been especially active...." We wouldn't want to scare people by telling them that the McCormick Fire has been especially active. Let's tell them that the activity has been especially active. Great writing! 
• Competing with the complex fire for best example of redundancy, we have dry fuel moistures. Low fuel moisture would be better. The technical people think in terms of the percentage moisture content in the materials that make up the fuels for wildfires. But a good writer would simply say dry fuels.
• The problem with the final error lies in what it omits. Writing in passive voice commonly leads to ambiguity about who performs the action. 
• A voluntary evacuation has been issued in conjunction with the Tuolumne County Sherriff's Office....
• By the way, you don't issue an evacuation; you issue an evacuation notice or order.
• And Sheriff has one 'r', not two.
• The news release probably came from the US Forest Service spokesman, so I'll fill in the missing detail:
• Corrected: The Forest Service, in conjunction with the Tuolumne County Sheriff's Office, has issued a voluntary evacuation notice....

Writing That Bites

The next grammatical atrocity has too many errors for a complete commentary. The points listed below will have to suffice.

• The past participle of bite is bitten. The woman bit the crew member. The crew member was bitten.
• Grammatically, ...in Angels Camp that had wedged implies that Angels Camp did the wedging. 
• The correct pronoun for a person is who, not that. That implies that the thing referred-to is not human.
• Had wedged... and refused changes verb tenses in the middle of the sentence. Had wedged... and had refused adds parallelism.
• The order of the phrases should reflect the importance of the information. The location should not interrupt the actions. A better version of the opening sentence would read,
• An ambulance crew member was bitten while attempting to rescue a woman who refused police orders to come out after wedging herself between two boulders near Angels Creek in Angels Camp.
• The sentence still uses a passive verb, which renders it boring. Splicing too much information into a single sentence makes it even worse. A best version would read,
• A woman bit an ambulance crew member who was attempting to rescue her near Angels Creek in Angels Camp. She had refused police orders to come out after having wedged herself between two boulders.
• The lack of a comma in referred to as the "Paradise" area for a female that... implies that the name refers to a woman. The resulting double entendre should bring a smile to dirty minds.  
• The lack of a comma in a steep ravine who had lodged herself implies that the ravine is a person and that the ravine did the lodging. Again, the writer interrupts the action by inserting the location prematurely in the sentence. A better version of the sentence reads,
• Once at the scene, they found a 21-year-old woman who had lodged herself in a crevasse between two large rocks near the creek at the bottom of a steep ravine about a half mile from the roadway.

The next sentence secured this article's place on my grammatical wall of shame.

• Unable to sit still and while making animated, erratic movements, officers ordered....

Too much coffee, officers? 

The final paragraph opens with an equally awful (although not nearly as funny) mistake.

• It took crews nearly two hours through heavy vegetation and rough terrain, to safely remove the women (sic) from the scene. First, vegetation and terrain are not units of time. Second, the writer blunders yet again by stating the location too early in the sentence. The corrected sentence reads as follows:
• It took crews nearly two hours to safely remove the woman through heavy vegetation and rough terrain.
• Notice that when the obstacles are correctly placed, it becomes clear that from the scene is redundant.

That's it for now. I'm happy with my vent. I hope you found this either amusing or edifying. If you see other examples of atrocious writing, feel free to leave a link in the comments, below.


More to come, later.

Copyright 2017 Richard Wheeler

Nit of the Day: Panes vs. Panels

A member of LinkedIn's Technical Writer Forum asked, I want to find out the difference usage of these two words: pane and panel. e.g. There are two panes or panels on this screen. You can place a dockable panel (not pane) anywhere on the screen. (sic)

A panel is a flat, physical area, usually containing controls, receptacles, a display such as an LED or LCD screen, or allowing users to remove it for access to whatever lies behind it. A screen is, technically, a physical, displaying area of a panel.

A pane is a section of a window. For a physical example, a paned window is a window that is divided into sections known as panes. Originally, the meaning pertained to sectioned glass windows in walls. (Wikipedia).

Thus, panes in Word 2007 would include the title bar where it shows the names of file and of the application, a menu bar, a "ribbon" bar, the editing area, a status bar, and optional ruler bars.

Microsoft uses "task pane" to designate an area sectioned off from the main area of an application and used for some function. For example, in Excel 2007, if you click on Review, Thesaurus, Excel will divide off a portion of the editing pane to create a dialog pane so you can search for synonyms.

MS Office task panes are dockable: You can drag them to different borders of the window or leave them to float, independent of the application window. Thus, Office task panes can convert between panes and pop-up windows.

• Panes make up windows.
• Windows occupy the screen.
• The flat-panel display houses the screen.

The screen is both physical and virtual, whereas the panel is only physical, and the panes and windows are virtual.

To correct the question:

Better: There are two panes or panels on in this window screen. You can place a dockable panel (not pane) at any margin of the editing area, or you can leave it as a pop-up window anywhere on the screen.

Best: This window has two panes....

If the company style book differs, however, remember the Golden Rule: He who has the gold makes the rules.

----------------------

IT Metrics and Productivity Institute (ITMPI) Premium membership gives members free access to 400 PDU-accredited webinar recordings and waives the PDU processing fees. The library is growing at about 100 webinars per year. Check it out: http://mbsy.co/dPHm?s=e

The New Resume: For Experienced Workers

Long-term worker, expect resume-shock.

If you haven't explored the job market in five or ten years, you probably need a whole new resume. What works best has not changed, but what's commonly recommended has. Throw out all your old materials about resumes.

• Older materials explain the Functional style. Recruiters and hiring managers reflexively ask, "what is the applicant hiding?" and give functional resumes a quick toss.
  
  
• Many older samples used paragraphs; but paragraphs have given way to concise bullet points.
  
  
• Your descriptions of achievements, employment history, and objectives may need a radial re-write..

It's not about me.

Your Achievements and Employment History sections used to describe what you did. Now, every description must state how well you did it or how it will benefit the reader.

The same applies to the Objectives statement. Replace it. First, the application or cover letter should make it obvious which job you want. Second, emphasize what you bring to the pot luck, not what you hope others will bring. Your resume is a marketing device, not a Request for Proposal.

That's tough for long-term cogs of giant machines where managers rarely communicate the significance of the work. Restating my duties as accomplishments with numbers and results, and figuring out my work's significance from 10, 15, or 20+ years ago required a lot of research. But it has to be done.

Value propositions are in.

Look at the job description and at the company's mission and objectives statements. Figure out the business case for the job. How do the job requirements support the employer's goals?

Then consider your abilities that match the job requirements. Why does the employer want somebody with your skill? What is the value of your skill? Ask and re-ask what happens for the employer if your skill provides that value. Stop when you get past your sphere of influence, and take a step back. Now you can state the value you will bring by doing what you do.

Don't claim the VP's accomplishments. State that your redesign saved the final $2 million that made selling doohickeys profitable, but don't claim to have saved the Division (unless you really did). For example, if the required life of a satellite was seven years, you could describe how you contributed to on-board diagnostics that extended the life to 15 years.

Specifics build a case for the truth of your claimed abilities.

Set a time limit to avoid agism.

By the way, only go back ten (plus or minus) years. If you haven't lost the skills you had in ancient history, they've probably become obsolete. I break that rule. I divide my employment history into Recent Employment and Early Employment (>10 years ago) and go back all the way. I enjoyed and want to return to those older jobs. Without the older jobs, I can't support some of my claimed abilities. However, if I can support my claim to be qualified for a job based on my recent employment history, I chop out the Earlier section.

Let the shoe fit the foot.

This goes to tailoring your resume for each position. The combination format allows me to sort my Accomplishments so the most relevant skills appear at the top. It also allows me to delete distracting, irrelevant skills.

If you apply for a variety of jobs on a corporate site, however, they probably limit the number of versions of your resume. In that case, you have to keep each version of your resume longer and more general.

Less is more, but more is more, too.

Starting out, one page is reasonable. Short and relevant is best. A lot of technical managers want details, though. Making them get out a magnifying glass is not the way to do it. A veteran engineer who organizes a resume with lots of headings gets the "core competencies" across in a 15-second reading. If that 15-second read catches the hiring manager's interest, the applicant will probably get away with two or three pages.

Apart from the part about job objectives, Barclay's podcast provides a great overview.

Note: Most European employers and many American professions such as academia and research require curriculum vitae (CVs), not resumes. All I know about CVs is that they can run many pages.

Conclusion.

The worst resume mistakes of 2011 include describing what you want or what you have done. Every statement of proposed value, accomplishment, or history should demonstrate how you will support the employer's business. Keep it as short and as simple as you can, but include enough to support each claim you make.

For a good audio over view of resume writing (except that he still uses Objectives instead of Value Statements), visit The Job Stalker - PodClass III - Resumes.

Must versus Shall

Updated 2 April 2011

Many think "shall" wishy-washy and "must" unambiguous. They have it backwards.

Few understand the differences between "will," "must," and "shall." For example, since "shall" conveys a sense of weightiness, people often use it pretentiously when "will" would do.

The ambiguity of "shall" lies not in the word, but in confused vocabularies. "Must" has ambiguous timing, certainty, and force whereas "will" and "shall" imply future fulfillment. Additionally, "shall" implies certainty and authority.

A "must" may occur at any time, and its importance can range from zero to critical. One could say "it must have been," "it must be," or "you must obey." "Must" can imply reasons ranging from fulfilling a desire ("You simply must visit us!"), achieving an ends ("To retire comfortably, you must save"), or avoiding injury ("You must remember your anniversary"), to fulfilling a requirement ("The roses must be red"). It can also denote a high probability ("Since A, B, and C are impossible, the answer must be D").

A "shall" may occur only in the future relative to the time of writing, and it implies not merely prediction as "will" does, but it implies certainty or determination ("It shall come to pass that locusts will devour your grain..."). Legal and contractual language assumes satisfaction of the requirement, so "shall" denotes a command or a requirement that will, with certainty, come to pass. I did not say, "shall, with certainty, come to pass" because that would have been redundant.

"Must" carries ambiguity regarding not only timing and certainty, but also regarding consequences. Another way to say this is that "must" leaves open the question of "why?" whereas "shall" makes it clear that this is a contractual requirement. One might say "you must," but saying "you shall" implies "or else...." Shall implies a future, required or commanded action or condition, with consequences if not fulfilled.

"Must" is ambiguous. "Shall" has a narrow meaning and usage -- for those who understand the terms, at least.

Part 2.

I agree with using simpler language. "Shall" only applies to requirements statement such as

Writers employed by ABCXYZ Company shall only use "shall" to indicate requirements.

Dumbing writing down just because people don't grasp the precision of the imperative "shall" (or where to use it) crosses the line.

Someone asked, "isn't it always up to the client?" The client may have a style guide over which the employee has no influence, so sometimes, it is up to the client's preferences.

However, it is not always "all up to the client." Clients have the final say, but the Business or Engineering experts hire writers for their expertise in technical English. Technical writers should dig for expertise in their domain and tell clients what they need and why they need it. Otherwise, they should hand over their jobs to admins.

In a discussion, someone challenged me with definitions of "must" and "shall." He also claims that an Illinois Supreme Court ruling, PEOPLE v. GARSTECKI, cast doubt on the clarity of "shall."

From Dictionary.com

Shall

1. plan to, intend to, or expect to: I shall go later.


2. will have to, is determined to, or definitely will: You shall do it. He shall do it.


3. (in laws, directives, etc.) must; is or are obliged to: The meetings of the council shall be public.


4. (often in invitations): Shall we go?

Must

1. to be obliged or bound to by an imperative requirement: I must keep my word.


2. to be under the necessity to; need to: Animals must eat to live.


3. to be required or compelled to, as by the use or threat of force: You must obey the law.


4. to be compelled to in order to fulfill some need or achieve an aim: We must hurry if we're to arrive on time.


5. to be forced to, as by convention or the requirements of honesty: I must say, that is a lovely hat.


6. to be or feel urged to; ought to: I must buy that book.


7. to be reasonably expected to; is bound to: It must have stopped raining by now. She must be at least 60.


8. to be inevitably certain to; be compelled by nature: Everyone must die.

Neither #1 definition applies because both refer to a first person context, and I only defend "shall" used in third person sentences that state mandatory requirements.

Definition 2 of "shall," "will have to, is determined to, or definitely will" indicates confident prediction. Although this is not the applicable definition, it still leaves no wiggle room for non performance, should the reader mistakenly use this meaning.

Definition 3 has two points. "In laws, directives, etc." is not limited to laws. The IEEE has trended toward use of "shall." That applies to "directives, etc." such as processes, statements of work, and requirements specifications. Engineers aren't known for their flawless grammar, but this does demonstrate that in at least some usages, "shall" has taken on an unambiguous meaning.

("Shall" Def. 3, cont'd) "Must; is or are obliged to: The meetings of the council shall be public" repeats the idea that no wiggle room remains for non performance. The Illinois Supreme Court ruling in People v. Garsteki, does cite a Third Court of Appeals ruling that "shall" sometimes means "may" or "must;" but then it clarifies with a Second Court of Appeals ruling that "'shall' had a directory (strong advisory) reading when it was modified by the phrase 'whenever practicable.'"

In other words, "shall" means "mandatory" until defined conditions negate it. The meaning "may" was not inherent in "shall" itself.

Moreover, the ruling that the Illinois Supreme Court reviewed pivoted not on the meaning of "shall," but on whether the lower court observed exceptions and conditions contained in the relevant stature. It had little bearing on "shall" versus "must."

Definition 2 of "must" -- the first definition applicable to third-person usage as in requirements documents -- "to be under the necessity to; need to: Animals must eat to live," implies reference to a cause.

"Shall" avoids the question, "why?" by asserting authority whereas "must" leaves open the possibility of mitigating the reason. That's a dangerous ambiguity for creative types.

A creative astrohusband might address the cause by putting his cows in hibernation or might address the need by feeding his pigs intravenously, thereby circumventing the "must." The first applicable definition of "must," therefore leaves wiggle room for non compliance.

"Must" definition 3, "to be required or compelled to, as by the use or threat of force," fulfills the need of a compliance document.

Definition 4, "to be compelled to in order to fulfill some need or achieve an aim," parallels definition 2. The sense is not "mandatory," but "needed," which could be addressed in other ways. "Must" demands the question, "why?" Any term that demands more questions than it solves cannot be called "unambiguous."

Definition 5, "to be forced to, as by convention or the requirements of honesty: I must say, that is a lovely hat," would fit right into the structure of a requirement statement. Why must the operator place the box on the top shelf? Because that's his duty? Because that's where we've always kept it? You can't exclude this meaning, just from the structure of the sentence.

I admit, "must" definition 6, "to be or feel urged to; ought to," is conversational. However, some argue against "shall" based on how people process it. This meaning of "must" works (incorrectly) in a typical requirement statement. Definition 1 of "shall" does not. That renders disambiguation of "must" much more difficult. The same applies to definitions 7, "to be reasonably expected to; is bound to," and 8, "to be inevitably certain to; be compelled by nature."

The two (2) applicable definitions of "shall" imply unambiguously the certainty of a requirement. The seven (7) applicable definitions of "must" imply weight that varies from desire to compulsion.

As Garstecki states, if in 3rd-person use, "shall" means anything other than that the verb is mandatory, then it is superfluous; if it is there, it is there for a reason.

But I could be wrong.

Additional reading from both sides of the issue:

PEOPLE v. GARSTECKI, Illinois Supreme Courte, No. 106714, September 24, 2009. http://caselaw.findlaw.com/il-supreme-court/1272225.html

“Shall” Versus “Will.” Grammar Girl Episode 119, July 22, 2008. http://grammar.quickanddirtytips.com/shall-versus-will.aspx

The Judicial Council of California. http://www.courtinfo.ca.gov/jc/documents/reports/1004ItemA27.pdf

The US Food and Drug Administration. http://www.fda.gov/AnimalVeterinary/DevelopmentApprovalProcess/ucm078511.htm

Ministry of Economic Development (New Zealand)
http://www.med.govt.nz/upload/67526/changes_to_the_securities_regulations.pdf