Name Your Files for the Readers — If You Care

Filenames — A Trivial Time-waster that Adds Up

How do you react when you see a filename like 500002p.pdf? 

Is this a file that you want to open? 

Do you think that the author of the file cares whether you open it? 

This one's a little better, but not much:  BBP3.0FactSheetFINAL.pdf.

What Do You Want to Know?

When I look at a filename, the first thing I want to know is what it is. After that, I want version information. 

Some people put their initials first.  In a team folder, the listing will group the Jim files, then the Joe files, then the John files, and so on.  (And then there's Jack who sometimes uses JB and sometimes JEB.)

Then you have to search up and down the screen to find all the versions of the same file.  The larger the team and the longer the project goes on, the more this wastes time and leads to mistakenly working with outdated versions.

A government website has a folder of presentation files in this format:  

2014_05_15-Draper-6th-AGNC-Welby-final.pdf

Placing the date first is redundant because you could always sort by date in the file explorer view.  Apparently, the Welby made the presentation and worked for Draper, and the topic was some cryptic initialism.  Now, how are we supposed to find presentations on risk management among 74 files with names like that?  Do you have an hour to spend opening all those files?  

There's another human element. When a filename starts with initials or has a serial number instead of a name, my eye says, "random, meaningless letters." Then my amygdala says, "look away!" 

Sometimes my amygdala wins, and sometimes my cerebral cortex wins. That contest creates stress. wastes time, and sometimes blocks communication completely. 

If you have a Content Management System (CMS) or Configuration Management System (also CMS) such as SharePoint, you have ways around this.  You can add fields for author, date, version, and subject.  

Often, however, we are stuck with filenames.  Even if your team has a CMS, you will still sometimes wish to download a file to your own drive.  If you don't remember what's in that cryptically named file three months from now, will you even bother to open it?

Since I read from left to right, and since an alphabetical sort proceeds from left to right, I recommend the following name format:

topic - [rev or yyyy-mm-dd [24-hour time if needed] ] - initials

example

meeting notes, team, 2015-08-01, rev A, rw.docx

Filenames should be in plain English. 

When I download files, I hate seeing files with names like BB097834.pdf.  I should not have to download and open a file in order to determine whether I want to download and open it. 

And by the way, who is JS, and does he or she even work here any more?  Does it feel professionalI to use your initials?  How professional will it seem to others, two years after you've taken that big promotion at another company and nobody here remembers whom JS was? Spell things out.

Some content management systems assign garbage names automatically.  We cannot do anything about that.  And some authors write only for their own vanity.  They do not care whether anybody reads what they wrote.  Try not to obsess over it; I've already done that for you.

A filename is like a headline or the title of an opus.  

A good author or editor knows that Job One is attracting an audience and, therefore, puts a lot of effort into creating a meaningful, eye-catching filename. Which would the classical music lover in your life rather listen to?

• PITop066.mp3

or

• Sleeping Beauty, Peter Ilyich Tchaikovsky, opus 66.mp3

It's about more than efficiency. It's about consideration.

Copyright 2015 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

Hypnotic Language Patterns

Basic familiarity with hypnotic language patterns can help you defend yourself against politicians, advertisers, and salespeople who don't necessarily have your best interests at heart.

 Summary:

• Indirect hypnotic language avoids argument or resistance.  Instead of commanding -- you are feeling sleepy -- hedging and suggesting leave more choice to the subject.  For example, instead of telling the subject, imagine yourself, suggest, perhaps you can remember.
• Indirect hypnotic language gives freedom to interpret what is being said in a way that makes sense to the individual.  Instead of putting you on a beach, it lets you choose a peaceful place.
• This focuses attention inwards.
• The yes set is a series of self-evident statements that conditions you to agree with whatever comes next.
• Truisms can lead into a tag question to make the statement before it less direct and easier to accept.  It works, doesn't it?
• Splicing a suggestion to a truism, even if one phrases does not logically flow from the other, associates the truth of one phrase with the other.
• Illusory choices or double binds presuppose the same outcome.  Would you want to pay with cash or with credit?
• Nominalisations use words with ambiguous connotations to turn the mind inwards to attach individual meaning to them.

Language that bypasses disagreement and requires the mind to make subconscious choices prepares the mind to receive suggestions.  Hypnotic language then delivers suggestions in forms easily processed by the subconscious mind:

• Deliberate confusion
• Ambiguity
• Metaphors
• Puns
• Analogies
• Narratives