Embedded, etc.

1Embedded journalism is the practice of taking news reporters and placing or “embedding” them within military units so that they can report up-close on a war. In the process, they shift from being independent journalists to dependent, because the very people that the journalists are reporting on have to save them from death, dismemberment, and other career-limiting moves.

All workers are embedded. Doctors are embedded in hospitals, policeman in high-crime areas, teachers in schools, and musicians in concert halls. In our jobs and throughout our lives, we are surrounded by others, embedded among our co-workers, friends and family.

To be an outstanding technical and business communicator, you need to be embedded within a business that completely relies on your skills. Ideally, you should be embedded within a smaller company (one with less than 100 employees) where you are the only person who has these skills; where you are the entire business document development and management department, one that you have developed and nurtured. You will never have a better job than one you created.

Ideally, you will be in charge of:

  • the company’s online content including their website, LinkedIn and Indeed pages, and job postings (and if any of these don’t exist, you must create them)
  • developing and managing their internal business content including: company emails, newsletters, forms, staff lists, training requirements, job guides, signs, policies and procedures, and job descriptions
  • any other documentation or information that the company needs to properly function including: press releases, brochures, signs, online surveys, schedules, questionnaires, feedback forms, etc.

Now, did you see what I did in that last sentence? I ended it with etc., the lazy writer’s way of saying: “I can’t be bothered to properly complete this list so I will just use etc. and let the reader fill in the blanks.” If there is one term that should be banned in all writing, it is etc.

But we can admire etc. for its deeper meaning, which is that it represents the completion of the list or thought that it describes differently for each reader. That is, each person will read the same sentence ending with etc. and fill in with their minds what the etc. represents. Etc. is the ultimate split-personality multi-tasker.

A great embedded technical communicator is an etc. They anticipate your thoughts and needs, and fulfill them. They are flexible and adaptable and know what you want before you knew that you wanted it. They complete you, and document the whole process.

It’s no coincidence that the acronym of Embedded Technical Communicator is ETC.

(Those are my thoughts, etc., etc…)

6 expressions of nonsense

weasel2As an advocate of clear communication, certain phrases make my blood boil. They are weasel phrases because the speaker is trying to weasel out of what they really should say.

They often begin with the word “we”, itself a way of avoiding “I”, and therefore shifting blame and responsibility to others.

Here are 6 of my favourite weasel phrases:

Phrase: The system failed.

Example: It was no one’s fault that the child starved to death. The system simply failed to meet the child’s needs.

What the phrase really means: I don’t know or care who is at fault, or can’t be bothered to find out.

Phrase: We’ll consider…

Example: We’ll consider not raising fees.

What the phrase really means: I won’t even consider your stupid idea.

Phrase: Mistakes were made.

Example: Mistakes were made during the construction phase, causing the building to fall down and kill everyone inside.

What the phrase really means: We don’t want to tell you who messed up.

Phrase: We encourage…

Example: We encourage the Iranian government to stop torturing people.

What the phrase really means: I know you’ll ignore me completely, so I’ll just ask you to do it, with no consequences if you don’t.

Phrase: My ‘ask’ is…

Example: My ‘ask’ that we have it done in 30 days.

What the phrase really means: I’m trying to sound impressive and clever by converting a verb into a noun.

Phrase: I’m sorry if/but….

Examples: I’m sorry if you were offended;  I’m sorry but that was not my intention.

What the phrase really means: I’m not sorry.

Summing up: My ‘ask’ is that I encourage you to stop using these phrases, but if you don’t, then the system has failed, mistakes were made, and I’m sorry if that disturbs you.


Write on, dude

Surprised expression on a baby boys face whilst getting into mischief on a laptop computer

It’s hard to work up the mental energy to write a blog entry. Writing is like exercising, eating well, or going to the dentist for a root canal: you don’t want to do it, it’s a pain in the butt, you’d prefer to put it off, but it’s good for you.

Here are four things you can do to be a better writer:

1. Make the time. This is the hardest step: to schedule time in your day, plunk yourself in front of a computer and start typing. We all have busy lives; the trick is to start small and build yourself up.

Start with one five minute session a day. Bang away randomly at the keyboard. Get used to the feeling of writing. Then, when you’re ready, increase it to ten minutes a day, then fifteen, and on on. You’ll reach a point where you’re mental flow is so strong that time vanishes, and hours pass like minutes. If you can write one to two hours a week, that will be quite a lot writing over the months and years.

2. Write about what you know and like. Write about the subjects that you find interesting or challenging. Everyone has different interests and tastes. Write about your particular “fetishes”.

3. Make connections. I enjoy seeing the connections between very different things, for example, between philosophy and technology.

What are your skills, interests or things that you are passionate about? How can you connect these? Even the act of trying to find a connection will get your mind in the creative zone.

For example, if you’re into politics and web design, write about what makes an effective political website. If art is your thing, write about how to achieve an artistic balance in your design. If you like technology (and who doesn’t?), write about how technology is influencing web design and vice versa. The combinations are limitless.

4. Know that it doesn’t have to be perfect. Many people hesitate to start writing because they don’t want to create anything that is less than perfect. The reality is that perfection exists (at most) in two subjects: philosophy and mathematics. To wait until something is perfect is to wait forever.

Yes, you should schedule time to review and edit your work, but at some point, the writing has to stop, and you’ve just got to take a deep breath and click that Publish button. Remember that any article that is written is infinitely better than a superior article that is never written.

Here’s hoping that you have “The Write Stuff”.

Easy as CSS 1-2-3


Click to view the CSS generator

CSS (Cascading Style Sheets) is the styling markup language that works with HTML to give web pages their look and feel. CSS is currently at version 3, which, being a relatively small number, would imply that it’s only been around a few years, perhaps 3 or 4.

Amazingly, CSS it was a standard proposed way back in 1994, and first released in 1996. CSS followed two years later in 1998, then in 2011, version 2.1 was released.

I have no idea why it would take thirteen years just to deliver a point release. It may have been because at the same time, starting in 1999, work started on 3.0, which still continues to this today, sixteen years later.

CSS 3 is really quite amazing. Many of its features are pure “eye candy” which would previously have been done using javascript, a relatively complex programming language.

Some of CSS3’s new features include:

  • animations and transitions
  • rounded corners
  • images for borders (rather than just plain lines)
  • box and text shadows
  • gradients
  • support for RGBA colour opacity
  • element rotation
  • multi-column layouts
  • embedding of web fonts
  • box sizing
  • media queries
  • selectors
  • multiple backgrounds
  • 3D transforms

As awesome as many of the features are, they should be used sparingly. We can’t forget that the main purpose of a website is to clearly convey information. Too many visual distractions will interfere with the readability of the text.

I can’t wait to see what CSS 4 will be like. However, at the rate that new versions are being released, it may not be available until the next century, at which time the computers will rule the world, so we won’t have much need for style sheets anyway.

How to lighten your backpack

backpackIf there’s one thing I hate, it’s carrying around a lot of stuff. I remember in college in the 80s having to carry my binders and textbooks around in a backpack – what a pain in the neck, and back.

Computers and the Internet have liberated us from having to carry around so much stuff. You can buy e-books (which are a bit lighter than regular books) and write notes in a document rather than on paper. But these advances have led to another problem: co-ordinating all your information and documents over several devices and locations.

Being a technical writer, I love to document everything, so I have hundreds of documents for all my personal needs. I need to be able to access this information:

  • in many locations – home, school, and work and
  • across multiple devices: my laptop, tablet, and phone

In addition, I want to be able to easily recover from what I call “The Terminator Scenario”. This occurs when your computer and backup drive both die or are stolen. I’ve known many people who lost everything when their hard drive died, because they forgot it was a moving part, and all moving parts eventually fail. It is only after this traumatic experience that they learn to back up their files.

But backing up to an external hard drive, while a good practice, does not protect you if someone breaks into your home and steals both your computer and hard drive, or if both are consumed in a fire, flood, tornado or some other natural disaster. It’s critical, therefore that all your files also be copied to the cloud.

I’ve found using Google Drive with Dropbox is an excellent solution. I use Google drive (formerly called Google Docs) to store all my documents and spreadsheets that don’t contain any critical private information. Although Google Docs is mainly used to store Google documents, you can store any type of document on it, making it a handy backup tool.

Google Drive gives you 15GB of storage for free; you can upgrade to 100GB for $2 U.S. per month, the best deal I’ve seen for online storage. You can also install a Google Drive application on your desktop that stores and synchronizes copies of the files on your hard drive, providing yet another form of backup.

I use Dropbox to store most other types of files. It gives you 2.5GB for free; you can upgrade to a whopping 1 terabyte (that’s 1,000 gigabytes) for $119 CDN per year, so it’s more expensive than Google Drive, but better integrates with your current file set. It’s great for storing any type of file and allows you to easily upload and download files to and from your desktop.

I use Google Chrome because a) it’s a great browser and b) once I log in, all my settings, bookmarks and Chrome applications are automatically loaded. This is especially handy when I’m logging in to different devices, including those that are not my own, such at a friend’s or at hotel.

Wherever I am, I use Google drive to make notes. I can then review and update them at home because they are the same files. I also use Dropbox to upload and download the project files. Again, whatever I work on at school, I copy to my Dropbox folder and it’s automagically there when I get home.

Finally, I use Google calendar to remember appointments, Google Maps to not get lost, and, of course, Google Mail (Gmail) to access my email anywhere. These apps you’ve probably heard of, but did you know you can use Google Keep to store simple lists?

As you can tell, I’m a bit of a Google nut. I think if I ever have another kid, I’ll name him or her Google.

(Maybe that can just be their middle name….)

University vs. college


Click image to learn the truth about university

Check out these actual degree programmes offered by various institutions of “higher-learning”:

  • David Beckham studies – Staffordshire University, UK
  • Doctorate of Philosophy in Ufology – Melbourne University
  • Surfing Studies – Plymouth / Melbourne
  • Queer Musicology – UCLA
  • Star Trek – Georgetown University in Washington
  • The Science of Harry Potter – Frostburg University
  • Learning from YouTube – Pitzer College

Don’t get me wrong – universities are absolutely essential for people who want to learn a traditional professional such as law, medicine, dentistry or engineering. The problem is that there are many thousands of students who are not enrolled in such programmes, and end up taking useless courses like these.

Some argue that university is useful for young high school graduates who aren’t certain what they want to do in life, and therefore just want to explore ideas in general. The problem with this is that university is a very expensive way to gain knowledge. These individuals could easily spend a year exploring various professions and meeting the people who work in them. They would gain much more valuable knowledge than anything in university, it wouldn’t cost them tens of thousands of dollars, and could actually lead to work down the road.

That’s why I’m glad to be a teacher at Humber. Its standards are as high as any university, and it offers practical programmes that can lead to employment. While it’s true that no amount of education can guarantee you a job, you’re much more likely to get one after completing a college programme than learning 16th century French poetry.

The 22 senses of technical communicators

The Five Known Senses

Humans have five senses, right? Well, not exactly. It’s a common belief that the only senses are sight, hearing, smell, touch, and taste. But scientists now know that we have so many more senses including:

  • equilibrioception – the sense of balance, which keeps you from falling down
  • thermoception – the sense of hot and cold
  • proprioception – the sense of where your body parts relative to other body parts; this sense enables to touch your toes with your eyes closed
  • nociception – the sense of pain
  • chronoception – the sense of the time

Note that these are just senses that have names. There’s practically an infinite number of unnamed senses, including a sense of:

  • hunger
  • thirst
  • exhaustion
  • suffocation
  • pressure
  • danger
  • morality
  • intuition

Technical communicators have even more senses, 22 to be exact:

Senses related to basic informational elements:

  1. fontioception – the sense of the correct font to use
  2. titulioception – the sense of the correct heading to use
  3. blancioception – the sense of the correct use of white space
  4. graficioception – the sense of when to include an image in a document, and the formatting of that image
  5. referencioception – the sense of when and how to use a cross-reference

Senses related to major informational elements and sections:

  1. definitiocepetion – the sense of how to describe a concept, term, or idea
  2. laboriocepetion – the sense of how to document a task
  3. diagramioception – the sense of how to create a meaningful diagram
  4. glossariocepetion – the sense of the terms to include in a glossary

Senses related to the structure of a document:

  1. indicioception – the sense of what terms to index and how to correctly structure an index
  2. partitioception – the sense of how to break up a large block of text into separate sections, or a large document into sub-sections
  3. lexioception – the sense of what text to conditionalize
  4. recylioception – the sense of what text to reuse or single-source
  5. darwinioception – the sense of how to structure information using DITA, the Darwin Information Typing Architecture XML language
Senses related to the reader:
  1. humanioception – the sense of the typical reader of the document
  2. intellengencioception – the sense of the reader’s intelligence
  3. curiosoception – the sense of how the reader will search for information

Senses related to general communication:

  1. practicaliocepetion – the sense of what is practical and meaningful information, and what is not
  2. presentioception – the sense of what information is current and up to date
  3. imperfectioception – the sense of information that is incomplete or inaccurate
  4. obfusicatiocepetion – the sense of a lack of clarity or meaning
  5. simplicitocepetion – the sense of simplicity in communication
The most important sense of all: clairitariocepetion – the sense of clear, effective communication

The Documentation of a Lifetime

The recent passing of my father resulted in many things. A funeral, speeches that tried to summarize his life (as if one can summarize a life within a few minutes), burial, grief and mourning. It also resulted in one of the largest, most complex and challenging documentation projects I have ever encountered.

My father was a brilliant man, university educated, successful, intelligent, a great speaker, and also extremely organized. He left behind various papers contained in two 2-drawer filing cabinets, two small lockboxes, and a couple of cardboard boxes. The paperwork included various legal, insurance, tax and financial information, bills and statements, and other assorted papers. I estimated there was about 3,000 pieces of paper in total; a literal tsunami of documentation.

Now, to be fair, it was somewhat organized. Items were placed in drawers marked for the lawyer and the accountant. However, when I began actually reviewing the papers, I discovered that the collection was sheer chaos.

The main problem was that there were many papers which did not need to be retained. These included bills and statements that were many years old and therefore had no value. In addition, there were many of the informational inserts and brochures that come with statements which are generally quite useless. You can find the information within these either online or through a phone call. I estimated that I discarded almost 95% of all the papers, filling several garbage bags.

The remaining papers had to be meticulously examined and properly filed. I purchased several cardboard banker’s boxes and a box of 100 legal-size file folders and began organizing the papers into individual folders, such as: Banking, Insurance, Investments, Utility Bills, Legal, Tax, and so on. The entire process took about three full days. I had to reverse-engineer what my father was thinking, and then organize the papers accordingly.

However, that was not the end of the project. For the purpose of organizing all these papers was so that that my mother could bring them to her various professionals (her lawyer, financial advisor and accountant) and be able to easily supply them the required documents. Organizing the documentation was not enough. I also had to create an entire set of electronic documents that described these paper documents, how to manage them, questions to ask her professionals, important things to do and so on. I also created documents of a more personal nature, including links to the various obituaries and speeches, and inspirational information, a sort of “Widow’s Toolkit”. It sounds strange, but my mother found it helpful.

However, this is not not the end of this documentation project. My mother and I will continue to work together so that when the time comes, all of her paperwork and information will be in order. Never again do I want to go through the pain of organizing a mountain of information after a parent has died. It is an unbearably tedious and painful task.

Therefore, everyone, no matter what age, should organize all the information that is important in their life. This includes:

  1. A to do list describing everything that needs to be done upon your death.
  2. A list with phone numbers of all your important contacts including your lawyer, accountant, financial advisor, spiritual leader (priest, rabbi, imam, and so on) and your primary doctor.
  3. Information about all your bank accounts, credit cards and financial investments.
  4. Documents for your lawyer – your will, marriage, birth certificate, passport, health card, and power of attorney in this folder
  5. Life insurance information, policies and amounts
  6. Tax documents for your accountant – these include old tax returns and related documents, which you must keep for 7 years
  7. A living will describing how you want to be treated if you are terminally ill, instructions for your funeral, and any parting words for your loved ones
  8. Your home and auto and insurance policies
  9. Logins and passwords – these should be stored in a password protected document and should include not only your online passwords, but passwords for your phone, tablet, computers and any of your other devices that require a password
  10. Info about your Canada Pension Plan, Old Age Security, or any other pensions you have
  11. Health plan information
  12. A list of all calling cards, rewards cards, memberships and subscriptions
  13. Documents related to your property: the house sale, deed, mortgage, assessment, letters of sale, and land survey
  14. If you have pre-planned your funeral (which is advisable to do to spare your family a financial and emotional burden), information about the funeral home and the package you have selected
  15. TV, phone, realty tax, hydro, gas and other utility bills
  16. Miscellaneous documents
  17. Warranties and any other important bills

Any financial, banking, insurance, legal, tax and other important information should include:

  • the name of the institution
  • the account number(s)
  • the balance of the account (if applicable)
  • the name and phone number of the primary contact

Organize the printed documents in a clear, easy to follow file folder system, with the folders in alphabetical order. At the start of every year, discard any documents you don’t need.

Maintain as much information as you can in a single password-protected Word document, then give your loved ones that password! Review this document every year (perhaps on your birthday) to ensure it’s up to date.

By documenting your life, you’ll ensure that your relatives will not have to go through the pain, frustration and anguish of having to sort through, decipher and decode this mountain of information.

In doing so, you’ll finally solve life’s ultimate documentation problem. And don’t you want to enter heaven with all your docs organized?

Sugar, Salt, Fat

Salt Sugar Fat: How the Food Giants Hooked Us is remarkable exposé on the food industry written by Pulitzer Prize-winning author Michael Moss. The processed food industry is a monster, with over a trillion dollars a year in sales. Sugar, salt and fat are together more addictive than any one of these ingredients alone. Moss describes in great detail how the food industry systematically manipulates these three ingredients to get consumers hooked on their products. As a result, many North Americans are obese and have multiple health problems, including an increase in the occurrence of diabetes in children.

Food scientists use cutting-edge technology to calculate the “bliss point” of their products. This is the precise ratio of sugar, salt and fat that the body is programmed to seek out and is combined in such a way as to make the food very tasty.

Documentation does not contain any food ingredients, but can be sweet, salty, or fat. Sweet documents are ones with much style, but little substance. They are dripping with exotic and unreadable fonts. They have dreadful colour schemes, such as a bright red font on a deep purple background. They may have endless animations or even sound, further distracting the reader from obtaining the pure information they require. They are a sugary and sticky mess, dripping with confusion and disorder.

We all know that salty food makes us thirsty. Salty documents are ones that make the reader thirst for more information. They do not answer the questions that the reader was asking, or only partially answer them. They may answer the question but in an unclear way. They may have the information the reader seeks but are structured in such a way that the reader cannot find it. Salty documents leave a bad taste in the reader’s mouth.

Fat documents are bloated. They contain too much information and too many words. They are over-documented, over-engineered and over-worked. They are a 200 page user guide when a 6 page quick-start guide would have sufficed. They are often written by engineers and marketers who have no concept of minimalism. Instead, they practice “maximalism”, the deranged belief that more words are better than fewer. The only cure for this disease is systematic and ruthless editing, along with a healthy dose of self-control.

Sugar. Salt. Fat. What type are your documents?

Join my army

See the source imageI have an endless fascination with the military. The idea of a select group of strong, well-trained, disciplined individuals united together for common purpose is deeply engrossing. It is the ultimate example of the whole being greater than the sum of the parts, for no man (or woman) is an army.

The military is so vast that in most countries it is broken up into separate parts or divisions, typically:

  • regular army
  • navy
  • air force
  • marines
  • special forces, and
  • coast guard

However, even all these enormous parts (and all their many respective divisions and subgroups) must work together as a single unit. A country would be in chaos if its army was in conflict with its air force, for example. They all must work as one.

Now, most of use do not have the mental strength, courage and physical endurance to serve in the military. But we can all appreciate its discipline and fortitude. Even business uses military metaphors, when they talk about “going to war”, “taking no prisoners”, and “destroying the enemy”.

A technical communicator is a soldier, of sorts. We battle against misinformation, obfuscation, and incomprehensible or missing information. We fight for clarity, truth, accuracy, relevancy, brevity, practicality, efficiency and logic. Ultimately, we fight for our end users when they have no-one else to defend them.

I am currently building an army of technical communicators. If you live in the Greater Toronto Area, email me your resume. Once I’ve confirmed you have the required experience, I’ll add you to my email list. I regularly receive job updates from a number of recruiters and distribute these to the list.

Dare to join the army of informational warriors. Enlist in the technical communication army today!