Technical Archives - TODAY INDIA

Technical Writing – About Flowcharts

“A route has no meaning in itself; its meaning derives entirely from the two points that it connects.” – Milan Kundera, 1929-, Czech Author, Critic

What’s a flowchart?

A flowchart can be defined as a graphical representation of a sequence of operations or steps. In other words, it’s an illustration of the various steps involved in a project or process.

Typically, a flowchart consists of a number of boxes, arrows, and text that combine to form a sequence.

Why create a flowchart?

The purpose of a flowchart is to show the various steps of a process in a snapshot. By looking at the flowchart, the viewer should be able to identify the various steps involved in the process.

Flowcharts can be very useful for a technical writer. If you’re working on a complex process, a flowchart can show you the various steps involved in that process. For example, you could be working on a manual on how to troubleshoot the Autopilot Flight Director system for the Boeing 747 aircraft. There are various steps involved in troubleshooting this system. Each step has multiple sub-steps. By creating a flowchart, you can quickly see which step takes place at what stage in the process.

How to create a flowchart

When you’re working on a complex project, creating the flowchart itself may be a time-consuming task. Here are six simple steps you can follow to create even complex flowcharts:

1. Start by defining the end result of the process or project. The end result could be anything such as completing a user manual, writing a complex software process, installing a new part, or performing a test.

2. List the various steps involved to achieve the end result. This will take some research. In complex processes, each step could have a series of sub steps. The steps involved to create a user manual could be:

a. Meet with SME

b. Research existing documentation

c. Videotape the procedure

d. Take photographs

e. Create illustrations

f. Develop the user guide

g. Test the user guide

h. Make changes/adjustments

i. Deliver final product

3. Define the starting point of the process of project. This is the first step that starts of the process. For example, the first step could be project planning or research.

4. Write down the starting point and the end result. Both of these should be in boxes with some space in between them. Adjust this space according to the number of steps and sub-steps involved in the process.

5. Draw an arrow from the starting point to the end result.

6. Along this arrow, list the various steps in order that are needed to go from the starting point to the end result. Include any sub-steps as needed.

Some processes may have multiple branches of steps involved. For example, to get from Step 1 to Step 2, there could be three options. You would illustrate this on the flowchart as three separate arrows going from Step 1 to Step 2.

A flowchart is like a roadmap. It has a starting point (A) and an ending point (B). Your objective is to get from Point A to Point B. The flowchart tells you what’s involved in the process.

For a technical writer a flowchart can be a very useful tool to illustrate various operations and processes. Before you start your next project, see if you can illustrate the process via a flowchart. It will make life easier for you and your manager or client. The end result will be a better project which is good for your target audience.

Note: Microsoft Visio is a good software for creating flowcharts.

Technical Writing – The Difference Between a Flyer and a Brochure

These terms are sometimes used interchangeably, but it’s pretty well established in the tech writing business that there’s a difference. It’s not that one is better than the other, but, generally speaking, they have different uses.

Flyer (also leaflet and handbill)

A flyer is a single sheet of paper, usually 8 1/2 x 11 (A4), used to get information to a large number of people inexpensively. Flyers are popular for small scale advertising.

They’re often, quite literally, throw-aways because they’re handed out at random or posted in public places in the hope they’ll be read. If they’re intended to be posted, such as on a bulletin board or put up in a window, they’re printed on one side only. If they’re going to be hand held or mailed, they can be printed on both sides.

The purpose of a flyer is to provide a limited amount of information for a limited time at relatively low production costs. Some common uses are:

announcements of social or commercial events
product information such as a spec sheet left in new cars
fact sheets distributed at a press conference

While desktop publishing has made it easy for non-professionals to produce quite sophisticated flyers, many businesses rely on professional writers and graphic artists for the copy and layout of business flyers.

There is some disagreement on whether a flyer and a flier are the same thing. The preferred usage in Standard Written English is that a flier is someone or something that flies.

Brochure (also pamphlet)

Brochures are normally more sophisticated than flyers and more expensive to produce. As much time, effort, and expense can go into producing a quality brochure as producing a short video. Businesses produce millions of brochures every year, and a skilled brochure writer is well paid.

Brochures are used as sales or information resources that may be retained and read a number of times by a specific audience. They’re commonly displayed in racks at airports, hotels, and doctors’ offices, but as random as this seems, it’s expected that only the people interested in the subject of the brochure will take one.

They’re not intended to be throw-aways. They’re widely used as follow-ups to initial sales contacts and as supplementary information sources. An insurance company, for example, might use one brochure as a sell-piece and later mail a different brochure to provide details of its policies to a person who has indicated interest.

There is no limit to the size or shape of a brochure, but the most common format is a single sheet of paper folded once – to create four panels – or twice – to create six panels. The first format is most often called one-fold or bi-fold. The second one is usually called tri-fold or tri-panel.

Technical Writing – Definition of Copyright and Copywriting

Definition of Copyright and Copywriting

You can apply for a copyright or you can apply for some copywriting, but they’re totally different things. In the first case, you’re asking for a document that gives you the right to publish something. In the second, you’re asking for a writing job. Writers often get them confused.

Copyright

A copyright is a legal document issued by the Copyright section of the United States Patent Office. It states that the person named on the document as the author owns the right to publish the written material designated in the document. That doesn’t mean that the person named actually wrote the copy, only that he or she has the legal right to publish it.

It’s not necessary to copyright anything. Legally, as soon as a person commits words to paper, they’re protected by a copyright whether a government document has been acquired or not. Practically, if you write something, and I apply for and get a copyright on it, it’s going to be tough for you to prove that you wrote it.

From the tech writer’s POV, it’s a little different. The law says that work prepared by an employee within the scope of his or her employment, or a work specially ordered or commissioned is a “work made for hire” and the employer is considered to be the author. If you get paid to write something for someone else, you don’t have a right to it.

In its correct forms, the word is:

– copyright: the right to publish

“She owns the copyright to that book.”

– copyrighted: the condition of being covered by a copyright

“You can’t publish that because it’s copyrighted material.”

– copyrighting: the act of obtaining a copyright

“I’m copyrighting this even as I write it.”

There is no such form as copyright or copywritten correctly associated with this definition even though the Microsoft Word Spell Check accepts copywritten as a correct spelling (but doesn’t say for what), and copywritten shows up all over the Web in place of copyrighted.

Copywriting

Copywriting is the act of creating copy or content. Generally, the term refers to writing in the sense of creating non-technical material. It’s different from the kind of writing tech writers do. Some jobs that call for copywriting are marketing brochures, magazines, newspapers, and consumer-directed communications. If you’re a writer, you might be a copywriter.

Bonus

Here’s another comparison to be careful of. If you want to write plays, you want to be a playwright. Yes, that’s right. You have to write wright when you’re writing about writing plays. We almost never use wright by itself. It’s used mostly in compound words such as wheelwright, millwright, or wainwright. We do see it a lot as a name; Frank Lloyd Wright or Wright/Patterson Airbase.

Wright has the same history as Smith. A smith was anyone who worked some kind of metal with a hammer; blacksmith, tinsmith, silversmith. A wright was a craftsman who made something. The name of the occupation became the name of an individual.

A person who makes plays is a playwright. True, he may write them, but he’s not a playwright. I guess you could argue that a person who writes copy is a copywright, but it’s not used that way.

Technical Writing – Definition of Demographic

Definition of Demographic

Frequently, a client will specify a target audience by talking about the customer profile. This is a way of talking about the demographics of the people in a consumer group. One purpose of a demographic is to find out what specific consumer segments exist in the overall population. Another is to have enough information about a typical member of a group to provide a kind of mental picture of an individual within the larger group. This information allows for the development of a marketing strategy and a marketing plan.

In ordinary use, a number of variables are taken into account when we talk about a group’s demographics. Commonly used variables include:

race
age
income
disabilities
type and number of designated products in the household
education level
housing status: own, rent, condo
employment status
geographic location
recreational preferences
buying habits

Each of these variables can be given more or less weight depending on the product or service involved. For example, a magazine publisher might consider a marketing campaign aimed at a demographic that includes single Asian men between the ages of twenty-five and twenty-eight employed in the aero-space industry living in Northwest US. This is potentially a large segment of the population.

On the other hand, if a company has a product that is expected to appeal only to Serbo-Croatian females between the ages of eighty-five and ninety who hold doctorates in Antarctic Economics and live with their parents, a demographic study might indicate that the potential market is too small for a major marketing initiative.

Let’s Get Picky

Every word has a specific meaning and that no two words ever mean exactly the same thing. And we still believe that’s true – except when it isn’t.

The word psychographic, technically, includes all the information in a demographic plus a lot more. A good marketing dictionary will define psychographics as a way of dividing consumers into groups based on attitudes, beliefs, values, personality, buying motives, lifestyle, and a number of other attributes.

Technically, demographics is a sub-set of psychographics that measures only age, income, and occupation. Practically, though, you’ll very seldom hear the word psychographics in a meeting because most people in marketing either don’t know or don’t care that there’s a difference. Demographics has become the industry shorthand that encompasses all of the elements of psychographics.

The Four Cardinal Points of Any Good Writing: Expression, Content, Organization & Technical Accuracy

Every piece of writing that is judged to be good must have these four cardinal factors; otherwise the writing will fall flat regardless of its intended purpose. Remember the intent of your writing should be to inform, instruct, entertain, solve a problem or show how to achieve a goal or objective. Always write for your target audience and not the internet or the search engines. When you connect to your audience, the rewards come back to you. The four factors are: Expression, Content, Organization and Mechanical Accuracy.

Expression: This is how you project your writing for the world to see, read and evaluate. Good writing is a craft. That’s why writers are called wordsmiths. A picture may be more than a thousand words but it also takes words to create pictures in your reader’s mind. This is the first factor that attracts audience to your writing just as bees are attracted to nectar. You may have heard that you must write to express and not to impress. Don’t write for ego; write for your audience with clarity and simplicity–so that everybody can understand your perspective and subject matter. People don’t care how much you know until they know how much you care. Expression is an art form. You must use your words to connect and create vivid images in your reader’s mind. People only apply what they understand. It all boils down to your choice of words, style, personality and overall thinking process. You must use powerful words and emotional triggers. Eliminate boring adverbs and dangling modifiers as much as you can. Use active verbs instead of helping verbs or adjectives. Active verbs make your writing to be more alive and dynamic. Realize that movement generates pleasure. Use active voice rather than passive voice. Thus expression is not just what you say but how you say it. However, what you say is also important.

Content: This is the factor that separates the mediocre from the masters. “Either you write something worth reading or you do something worth writing,” said Benjamin Franklin. Content is the substance and the essence of your writing. In short, content is the heart-beat of any great writing. It is the value you brought to the marketplace. People are value and quality shoppers. They want the best for the least amount of money. You have heard it said that in the internet, content is king. The story is the same everywhere. Content is the quality of the material you put out. This has to do with the key benefits the readers will extract from your writing to solve their problems or achieve their goals. As a writer, you must always ask yourself: “how can my writing solve problems or change lives?” A good writing that sells itself is writing with great content. Search engines love content. Therefore, put out good content that people love and seek. Then the search engines will locate you naturally and people will seek your offers. Let your content be fresh and original instead of recycled materials that flood the internet. Content is what search (and research) is all about. Having said that, you must also know how to arrange and organize your content so that the information is readable and digestible.

Organization: One of the most difficult things about writing is how to organize and arrange your thoughts. “Most writings are a few good thoughts drifting about in a sea of words,” said Jamie Buckingham. Organization is a product of coherence and consistency. How does your thoughts flow logically as in a flower? One idea must lead and link to the next. To be consistent, you need style manual as a guide. Therefore, try to plan your writing. Outline the key points or bare bone essentials you may want to develop before you put the flesh as you go. Let each paragraph contain a theme or one main idea. The flesh can be the description, examples or anecdotes to buttress your points. Organization is a process. It comes with practice, experience and writing intuition. You get better as you keep on writing. Formatting is a very important part of your organization. Arrange information in chunks.

That’s how the human brain process information. That’s why it’s called bites and bytes. Formatting is about headings, paragraphing, bullets, lists, typography, lines and spacing to create visual appeal for your readers. You don’t need to be a graphic artist to develop a good sense of organization. Did you notice that majority of HTML tags are formatting tags? Any good content and expression can fall flat without good formatting–it is a key part of your organization. The best way to learn this art is to glean from other good writings. After trial and success, it comes together with practice. Either you keep writing or you become a write-off. My watch word is: “Persistent practice prevents poor performance.” The more you write the better you grow as a writer. Practice does not make perfect; practice makes improvements and improvements make perfect.

Mechanical (Technical) Accuracy: This is fancy way of saying that your writings should be free of errors. Mechanical Accuracy is the Achilles tendon of most writers. They worry too much about the difference between colon and semi colon–causing paralysis analysis. This is the key reason why many people dread writing. Mechanical accuracy has to do with your typographical errors, spelling, punctuation and syntax. This is why you must have your writing tools: spell checkers, dictionary, encyclopedia and other reference materials. Remember that no writing is readable until it is free of errors. It is also a smart idea to give your writing to someone else to proofread and edit because of human factors. Overall most good writers are made in rewriting. The key lies in the principle of the 3Rs: revise, review and rewrite.

Your writing process is like preparing a good meal. All four ingredients must be present in your recipe before you create a balanced food for thought.

Learn Technical Writing – Definition of Letter and Memo

It has come to our attention that some people think of a memo as just a short letter. Not so! Specifics to follow.

That’s a memo. Maybe shorter than most, but it’s a memo and not a letter.

Letters and memos (or, memorandums) are similar in many ways, but they serve two different purposes. It’s important to know the distinctions in order to produce the type of document you’re asked to write.

First we’ll look at some shared characteristics. Both letters and memos:

– use similar format styles

– are sent as hardcopy by either an external or internal delivery system

– can be typed or printed from a computer file

– address one specific subject

– provide information to or try to bring about a desired reaction from the recipients

There are two very important characteristics that distinguish a memo from a letter. The first is that letters are specific and memos are general. That means that letters normally go to specific recipients. They’re written mano e mano. Memos are not usually considered to be private communication. They’re normally addressed to multiple recipients. There may be dozens, hundreds, or thousands of people who get the same memo. That means that the odds are much greater that a memo will be read by someone it isn’t addressed to than for a letter. Memos get put up on bulletin boards and left on tables. There’s nothing private about a memo.

The second is that letters can be as long as the writer wants them to be while memos are written in a very condensed manner with a lot of information in very little space. Nothing unnecessary is included. There’s no Dear Sir orYours truly in a memo. Just the facts.

A memo can have a number of purposes. It can:

– distribute news and information to multiple recipients

– convey thoughts or opinions for immediate reaction

– call people to action or to a meeting

The single, most important difference between a letter and a memo is that a memo is short and to the point.

Note: Technically, the plural of memorandum is memoranda, but you probably shouldn’t use it unless you’re writing in a very high-level, academic situation.

A Heart Pounding, Thrilling Adventure and Intro to Technical Canyoneering: Rappelling Coon Bluff, AZ

The amazing state of Arizona is known as canyon country and home to many beautiful and diverse slot canyons with sheer rock wall cliffs, deep natural pools, and breathtaking cascades and water falls. Many of these gorgeous canyons are still relatively unknown, rarely visited, and not that far off the beaten path to able to be accessed and reached in a day’s journey. In order to descend into these backcountry canyons is what “canyoneering” is all about consisting of hiking, climbing, boulder hopping, scrambling, swimming and rappelling, with rappelling being the most technical of all the canyoneering skills and also the most dangerous. Canyoneering thus becomes “technical canyoneering” when rappelling or the use of ropes are required in order to safely continue the descent and exploration of a canyon area. So if you’re looking for greater adventure and more of an outdoors challenge and the ability to further explore more of the beautiful and remote rock canyons of Arizona, then you’ll want to check out learning how to rappel where you’ll begin your venture into the exciting world of technical canyoneering!

Rappelling is defined as “a specialized climbing technique used to descend mountains or cliffs through the use of a controlled slide down a climbing rope anchored to the top of the cliff’s ledge. ” Rappelling is considered an advanced canyoneering skill requiring formal training and practice before heading out either with a guide or on your own. After having been recently introduced to the sport of canyoneering, I’ve been inspired to continue growing my canyoneering skills so that I can explore more of these remote backcountry canyons. So when a local hiking group called the Hiking Hikers Hiking Group (aka Triple H) announced that they were offering a beginners introduction to rappelling class at Coon Bluff Recreation Area on the Lower Salt River, I quickly and excitedly signed up!

Located about 17 miles northeast of Mesa, on the beautiful Lower Salt River in the Tonto National Forest, Coon Bluff Recreation Area is a scenic and popular location for camping, picnicking, fishing, and also wildlife viewing and bird watching. Along the flanks of the river and its lush riparian habitat, they say it’s very common to see bald eagles, turkey vultures, and even wild mustang horses that wander in from the desert in the early morning hours. To visit the Coon Bluff recreation area, a day use Tonto National Forest Pass must be purchased, at a cost of $6 per vehicle. You can purchase a pass before you leave either online or at your local sporting goods store, such as The Big 5 Sporting Goods.

So on a bright, clear November weekend morning, and after stopping to pick up a Tonto National Forest pass, I set out on I-17 South from North Phoenix to meet up with my good friends and fellow hikers for our 1st rappelling class and adventure. Coon Bluff, we learned, with its 92 foot sheer vertical rock wall cliff, is also a popular place for practicing rappelling skills whether you’re new and a beginner just starting out or if you’re more experienced and advanced. Being someone who has a real fear of heights I thought, oh my God, 92 feet? I felt so nervous and not even sure I’d be able to actually go through with it, at least not without a big giant push from behind!

After picking up our last friend in Gilbert, in the East Valley, we were finally ready to set out for Coon Bluff. To reach Coon Bluff from Phoenix the directions say to take route 60 east to the Power Road exit, then head north on Power Road, which turns into the Bush Highway. After about 12 miles or so on the Bush Highway you’ll first come to the Phon D. Sutton Recreation Site Road, but keep going another ½ mile, and on the left you’ll come to the Coon Bluff Recreation Area Road. We turned left and arrived at Coon Bluff at about 1:40pm, just in time for our 2pm, afternoon session Beginners Rappelling class.

We parked at the Coon Bluff Recreation Area parking lot, where we also met up with a few other class members who were just starting to arrive including our good friend and fellow TLC Hiking member, Dan Myers and his daughter. We got out, got our packs and gear together and after posing for a quick group photo, we started the short hike down the trail to the river’s edge at the base of the bluff and the 92 foot rock wall we would soon be descending down. The closer we got as we approached, the taller it looked too. From the river’s edge, while we were waiting for everyone to arrive and for the class to begin, we enjoyed watching as there were still people rappelling down from that day’s morning session class. Wow, I thought as I looked up in amazement. From the ground, looking straight up, you’d swear it looked like 200 feet!

Soon everyone had arrived and it was only a few minutes later that our event organizer and instructor, professional world mountaineer, Michael Marin, had arrived after having both rappelled down to the bottom themselves. In this introduction to rappelling class Michael expressed that we were going to learn all about rappelling technique, selecting and building anchors, tying knots, gear, terminology, what to do, what not to do, and how to get yourself out of a jam should you get yourself into one. But most importantly Michael began by stressing the importance of safety, safety and even more safety when it comes to rappelling whether you are new and learning or whether you are an experienced canyoneer or mountaineer. It’s carelessness that is the leading cause of accidents and death and is preventable by learning the essential skills properly and always using good common sense, he said.

After setting the foundation of safety first in everything you do when it comes to learning how to rappel, we were then introduced to the gear and equipment we would be needing and using for our first rappelling adventure. A list of the basic equipment you need for rappelling and which can be purchased at a local REI store are, 1) a good fitting harness, prices range from $40-$55, 2) a locking carrabiner, $10-$20, 3) a rappelling device such as a figure 8 or an ATC, $15-$30, 4) a 5ml prusik cord, for $10, and last but not least, and the most expensive piece, your climbing rope, which for technical canyoneering, and for beginners, they suggest a non-stretch, dry treated rope, ideally about 9-10ml and 60 meters or 180 feet in length, and runs in the price range of about $160, not including the rope bag you will also need for about $40. In addition, when it comes to packing the gear and venturing into wet canyons for technical canyoneering, backpacks start at about $129, and for securely storing your equipment and assessories its essential to have a dry pack to prevent water leakage and whether large or small, the prices range roughly from $10-$20.

With our harnesses and equipment safely and securely on, we were walked over to a tree behind us where Michael had ropes anchored securely and ready for us to begin learning rappelling technique and practice, while still on the ground, how the equipment works and why, as well as give us all a chance and opportunity to get comfortable with how to use the rope through the rappel device. You don’t need to “white knuckle it” he demonstrated, just guide the rope behind you with your right hand to your rear, then release pressure and resistance for greater speed or hold tighter behind you, adding more pressure and resistance for your brakes, to slow you down or to stop altogether. Once you understand how to utilize this technique, all you need to do is just lean back into your harness and trust your equipment will work for you. After everyone had gotten a chance to practice and felt comfortable enough to continue, we were given the okay to begin practicing our first real live rappel!

We followed Michael as he led us up the trail to the top of the bluff and what a beautiful view it was overlooking the entire Lower Salt River valley below. Wow absolutely gorgeous! After a few last minute tips and pointers about setting up anchors, how to set them up safely, where, and what types are best to use, both natural and man-made, we walked over the cliff’s edge where Michael introduced us to the dual ropes we were going to be using and spoke to us about the importance of redundancy when doing any type of rappelling or mountaineering especially for beginners, like us.

Now we were ready to start our first rappel. Michael asked, “okay who’s going to go first?” After a quick peak looking down over the cliff’s edge to get a photo of my friend Scuji waiting down below, I could hardly see him. That’s when my heart began racing and my palms started sweating. Wow, I thought, that was a really long ways and straight down too! I had so many butterflies and the longer I was up there, the more nervous I got. So I jumped in line quickly after my friends Carolyn and Bob and as I was starting to shake like a leaf, I walked over to the edge where Michael hooked me up to the rope and I was instructed to call down below, “on belay?”, then after hearing the call back, “belay on”, he said to call back again saying, “rappelling”. While keeping my eyes locked with Michael’s, I kept asking, “am I doing it right?” and as he repeatedly replied back, “yes, you’re doing it right, you’re doing good, keep going!”, and with his confidence and assurance, I started to slowly walk myself back off the side of the cliff, leaning back into my harness at the same time pulling the rope behind me with my right hand to keep my speed slow and my decent steady, but never once looking down, just focusing intently on what I was doing until roughly almost midway I heard a call from my friend Scuji who was yelling up at me, “Laura, look left!”. I hesitated then reluctantly looked down so he could get a picture. It was that moment that I realized I was actually doing it! Now it started feeling easier and I was even feeling comfortable enough to let loose of the rope a little and increase my speed, swinging a bit off the wall as I continued to grow closer to the ground. Wow, what an incredible and thrilling experience! Once I had made it safely to the ground, my good friend Bob was there waiting for me to help me unhook and I was again instructed to call back to the top, “off rope” to let the next person know that I was done rappelling.

After having completed my first rappel, I then waited for the rest of my friends and classmates to make it down safely. First came my friend Dan, then Scuji, as well as the rest of the remaining class members, as I continued to take as many photos as I could, capturing their first rappelling experiences for them. As the last members came down, the sun was starting to set and by 6pm, the last person had made it and the ropes were dropped signaling that class was officially over.

It was a really great day and an incredible experience and an excellent class organized by the Hiking Hikers Hiking Group (aka Triple H) and taught by our friend, professional world mountaineer, Michael Marin. A real heart pounding, palm sweating, thrilling adventure and excellent introduction to rappelling and technical canyoneering, I will never forget either! So if you’re looking for greater adventure and more of an outdoors challenge and would like to be able to explore more of the beautiful and remote back country rock canyons of Arizona, then I highly recommend learning rappelling and begin your venture into the exciting world of technical canyoneering!