Technical Writing – Dotting the “i”s and crossing the “t”s

One of the most important aspects of technical writing is the housekeeping chores – spell checking, grammar check, formatting, and proof reading. These may seem boring and not that important but they quickly differentiate a professional writer from one who has some writing talent. A misspelled word, subject-verb disagreement, wrong verb tense, reflects negatively on you, the writer. A plumber who installs a new sink doesn’t look good if he or she leaves you with a leaky faucet. Writing is your profession. You need to treat it professionally. Not everyone is a writer, but just about anyone can spot a spelling error or sentence that just doesn’t sound right.

Create a checklist to ensure that your documents meet the necessary requirements before their release, as in the following example.

Never rely just on your software’s spell checker. Spell checkers often substitute the wrong word. If you are not sure of the word’s spelling, use a dictionary to ensure that he word is spelled correctly. Make sure that all the “i”s are dotted and the “t”s are crossed. Writing is your profession. Do it professionally.

Technical Writing

Technical writing is a great profession for people who like to understand and explain how things work. While a lot of technical writing is focused on computers and software, technical writing includes financial, medical, pharmaceutical, tool crafting, and many other fields.

The craft of technical writing is simply to explain technical concepts in a manner appropriate to the intended audience.  For example, a technical writer may have to write a programmer’s guide for a 3D software program and also write the user guide for the novice. He or she may have to write standard operating procedures for clinical trial data entry or write a product spec sheet for a piece of equipment. The key is to understand the concepts and to use the appropriate language for your intended audience.

A technical writer also needs to explain both the process and the procedure. Process documentation explains how something works, for example, how a specific module in a home banking software program works. It may explain how the “check entry” module classifies checks written by category and explain other features.

The procedure documentation explains the steps needed to enter a check, select the category, and so on. The process documentation tells you what the software or piece of equipment can do; the procedure documentation explains how to do something.

People are auditory, visual, or kinesthetic learners. Auditory listeners learn by reading or listening. Visual learners learn by watching – images, diagrams, videos, etc. Kinesthetic learners learn by doing, hands-on learners. A good technical writer writes for all three learners whenever possible. The documentation, in addition to text (great for auditory learners), include images, illustrations, diagrams, links to videos for the visual learners, and procedure documentation for kinesthetic learners.

My Generation is Gone

While having coffee at the local Dunkin Donuts this afternoon,  I met a 91-year old gentleman named Tom. God bless him; he is in better  shape than me and wiser than me. During our conversation, he mentioned that at his age, all his friends are gone; they have all passed on. My dad use to say the same thing that his generation is gone. It’s a shame but that is part of life. Makes one appreciate the friends we have.

He talked about the old times in Revere and how times were nicer. He mentioned the street cars that passed through the city.

I am just 10 years more than half his age, but I remember the street cars. One aspect of local public transportation that I always liked is that it made people part of their community. Local public transportation brought a community together; people met and talked with each other on the street cars. It made life a bit slower which was a good thing. My dad also said that people were in a rush to go nowhere and we see that every day based on the way people drive.

Certainly we can’t go back in time; that is life. But it would be nice if people were part of their communities and people were more civil. That part of our past we can bring to the present.

And to my friends, I appreciate your friendship. As my dad said, “Give people roses while they can still smell them.”

Make Shabbos Personal

Shabbos is the Ashkenazi word for Sabbath or Shabbat in Hebrew. This day is a day of rest; it is a time for reflection. As our world becomes “always connected”, time for rest and reflection is very important.

People are addicted to their cellphones, laptops, and other technologies. We constantly check our email, take phone calls at all times of the day and night, and we text and Facebook constantly. These technologies and services are important but are they that important that they consume our lives?

I want to encourage people to join me in my “Make Shabbos Personal” campaign. You do not have to be Jewish or be religious. The goal is simply to encourage people to schedule some time each day for themselves. Shut off your cellphone during lunch. Use that time to read a magazine or book, or to just reflect and relax. Keep your weekends email and Facebook free; spend time with family and friends. For the spiritual or religious person, take some time for a spiritual workout. Say a prayer, read from the Bible or other religious books, and most importantly, “live the Bible” – take time and act as the Bible tells you to live your life.

My dad always said that people are in a rush to go nowhere. Deadlines are important but so are your health, your well-being, and your quality of life. Schedule some time for yourself.

Please share your thoughts with me.

Constitutional Questions

In my previous post, I introduced ConstitutionCafe. I would enjoy hearing your thoughts concerning these questions.

• If you could add any amendment to the Constitution, what right would it give Americans?
• The First Amendment states, “Congress shall make no law respecting an establishment of religion, or prohibiting the free exercise thereof.” When schools prohibit prayer in school, does this prohibit free exercise of religion?
• Should the Constitution include an amendment specifying official political parties?
• Should amendments have expiration dates in order to force Americans to review their rights?
• The Third Amendment states. “No soldier shall, in time of peace be quartered in any house without the consent of the owner, nor in time of war, but in a manner to be prescribed by law.” This amendment was written in response to the British forcing the Colonists to house soldiers at the time of the American Revolution. Is this amendment still necessary?
• Does the Constitution apply to illegal immigrants?
• Men wrote the Constitution. How would the Constitution be different if women wrote it?

In the spirit of respectful debate, please share your thoughts with me.

ConstitutionCafe

How important is the U.S. Constitution to you? How well do you understand the Bill of Rights? Newspaper forums and Facebook are filled with negative comments about political issues. The ConstitutionCafe provides the opportunity for people to have invigorating and polite discussions concerning the Constitution.

According to their website,

 Jefferson’s visionary antidote for societal stasis in American democracy, as he told the historian Sam Kercheval, was to take periodically “as a tally, every provision of our constitution, and see if it hangs directly on the will of the people.” Those provisions that turn out not to reflect the people’s will, he believed, should be entirely redone. “Let us then go on perfecting [the Constitution],” he urged, by supplanting “those powers which time and trial show are still wanting.”

Constitution Café springs from this idea: What if Jefferson’s radical proposal was put to the test in some way today? To be sure, he had in mind that this constitutional makeover would be undertaken every 20 years, and over 200 years have passed since he first proposed it. But better late than never.

I’m in the process of starting a ConstitutionCafe chapter in my community. How about you?

The Opera Guy

Some of the best music I hear is in the subway. Many talented musicians perform against the din of the trains. One talented singer I’ve had the pleasure to hear at the Blue Line section of Government Center  is Wesley Ray Thomas, a baritone, known as The Opera Guy. Wesley’s rich baritone soothes hurried commuters and opens their minds to the sounds of opera.

I hope you have the opportunity to hear this talented baritone during your commute. Take a moment to visit his MySpace page.