If you're new here, you may want to subscribe to my RSS feed. Thanks for visiting!

My very first Technical Writing job was with a company called Rene Perez and Associates, then located in Coral Gables, Florida. Rene’s company was an IBM partner and also based on the AS-400 mid-range mainframe computer system. His software was designed to help manage and control airplane parts and airplane maintenance activities for airlines such as Bahamas Air, Avianca, Virgin Atlantic, among others. The user guide was, next to the software system, the #2 asset of the company, because both marketing and support used the user guides written by Technical Publications, which was comprised of two people: myself and my boss, Jim Burke, who benevolently taught me the ropes of the industry, the system, and documentation in general.

A good user’s guide can be reused, indeed, by marketing departments, sales departments, training and customer support, and even programming! Everybody asks: where is the documentation on this module or program? So, we Technical Writers, as you can see, write “behind the scenes” but end up serving software companies in the direct line of fire. So, you are asking, how does one actually write the user’s guide? What steps need to be taken and what are its sections? OK, here is my reply…

One. Learn your system 100%. Am I asking too much here? Absolutely not. If you cannot learn all the intricacies of a computer program, then you cannot document it completely. The user’s guide will have major holes and flaws. Learn the system - see your time spent in this way as an investment in your career with the company you are serving.

Two. Politicize yourself with programming, quality assurance, implementation and training teams. Each of them will gladly share with you their trials, successes and failures as versions of the software are released to clients. This way, you can redirect your focus and how much you write about a certain module or aspect of the overall system.

Three. Divide and conquer. Look into the overall architecture of the system, and divide your manual in the same way. Do not try to reinvent the wheel. Does a pilot fish become the shark? Never…he just follows and gets his meal that way. As you follow the Architecture of the system, this will ease your documentation efforts greatly. People will follow your documentation in a way that is parallel to the system itself.

Four. OK - here are the sections of any given user manual: (1) Table of Contents, (2) Modular Descriptions and Step by Step instructions on “how to” do this and that, (3) Glossary of Terms, and (4) Index. You can also have an appendix or two, but I am against using them - especially if you can incorporate this information into the main body of the user guide. Technical Writers who include several appendices are often times lazy and unwilling to change the main document to make it better. A little effort will go a long way - trust me on this; it really does improve the user guide.

Five. Proofread, proofread. After you write your user guide, have anybody and everybody read it. I don’t care if you ask the company’s CEO or President to read the manual - you will be surprised at the diversity of feedback you will get. It is worth it - always. You will catch all sorts of things - and eventually - as the final version rolls out of your user guide - EVERYONE at the company will benefit - because they are the ones who have been asking for “the documentation” all along

Written by Keith Johnson September 17th, 2008 6 Comments »

As a Technical Writer currently taking on languages like Microsoft Visual C# and XML, I have noticed that there are skills essential to language mastery. Computer programming is dynamic today in ways unlike before, without a doubt. So, for those of you who are currently trying to expand your knowledge base with a new language or two, or you are brushing up on details of a computer language or two that you already know, here are some tips to keep in mind as you scale the mountain of computer programming:

One. Basic Logical skills. The most common forms of basic logic and decision making within programming are the do-while and if-then-else approaches. Here, the programmer needs to consider the choices available within the program in terms of direction and what the application should do at that particular moment.

Two. Top-Down Thinking skills. Generally, a computer system is comprised of different “sub” systems so a programmer needs to have some design or top-down thinking skills to see the program from the larger picture. Have I created modules or sub-systems that properly divide the system for optimum performance? Just like in Economics you have micro and macro economics, so it is with programming.

Three. Object-Oriented Language Thinking skills. Many or most of today’s languages are Object-Oriented, meaning that you are working WITHIN the framework of inheritance and polymorphism, among others. You can increase an application’s performance by appropriately accessing and using the inherent powers of the languages by working with wisely selected classes, methods, properties and things of these kinds.

Four. Attention to detail. Each programming language has detailed reference and keyword-type aspects that must be understood. For you to include a class or method, you need to code these items correctly, with the right syntax.

Five. Ability to read specifications. Programmers today often work with architects who do the actual system design and then the programmer must code according to these specifications. This is a challenging task because the programmer must be able to interpret the specs and then code so that the parameters given are followed and finally implemented.

Six. Ability to test. Most programmers today see themselves as coders and nothing more. A good programmer will always be a great asset to a software company if he or she can test the code written so that different data is presented and the code handles it correctly. Some programmers think testing is only for Quality Assurance, but sometimes programmers can see further into the application, and so their testing can actually be even more critical to the overall success of the application.

Seven. Dedication to documentation. Just like testing, many programmers think that coding is all that matters but really it helps the company when a programmer leaves nice comments in his or her code for future programmers. This way, as new releases are designed, others who will recode a module or application will be able to see into what was previously done.

Eight. Good business sense. Sometimes it is hard for us to extract ourselves from coding and then see the “big picture”. This is important. All programming ultimately serves a larger purpose where the application is going to help a customer or client in some way. It is good for programmers to subscribe to a blog or magazine that discusses market trends and needs for the market that he or she is serving.

Nine. Patience. This is not a technical skill, but a skill nonetheless that will take a programmer far. Coding is not easy, and so the more patience a programmer cultivates, the greater the success he or she will experience.

Ten. Perseverance. Along with patience, the skill and personal trait of perseverance is very important for programming success. Sometimes, many, many compiles will have to transpire before all bugs and errors are overcome and eliminated. Stay the course and stay focused with perseverance.

Written by Keith Johnson September 14th, 2008 5 Comments »

According to a few different surveys on the Internet, the following companies are considered to be the most profitable and successful companies, thus far, in 2008 (world-wide):

One: Microsoft Corporation ($14 billion in net profits)

Two: IBM Corporation ($10 billion in net profits)

Three: Cisco Corporation ($7 billion in net profits)

Four: Hewlett Packard Corporation ($7 billion in net profits)

Five: Intel Corporation ($7 billion in net profits)

Six: Oracle Corporation ($4 billion in net profits)

Seven: Google ($4 billion in net profits)

Eight: Apple Corporation ($3 billion in net profits)

Nine: Qualcomm Corporation ($3 billion in net profits)

Ten: Dell Corporation ($2 billion in net profits)

I would say that the ultimate challenge for businesses today is to be able to define oneself business-wise before the customer. So, the customer doesn’t have to wonder, OK, well now what exactly is this company and what does it do? I think this is reason behind the success of these companies listed above. They have succeeded in defining their “brand” and people and other companies know almost instantly what each of them represents, product or service wise. This is a great accomplishment.

If you have a business or work for a business of some kind, then ask this question: can our customer or client define us easily within a minute’s time? If the answer is “yes” then your company or outfit has done a good job in promoting its name or brand and this is great because this will generate a wave effect through the market and this will boost business. However, if this is not the case, then get started! Define yourself clearly, and help your customer “know who you are”. All of these companies listed above have done this, and this has surely helped them to rise about their competitors in the marketplace. Wishing you success with your business

Written by Keith Johnson September 13th, 2008 1 Comment »

Becoming a professional writer, ultimately, is the final result of many years of endeavor. You cannot just take a class and *become* a professional writer, like you can take education classes and become a teacher. Writing is a dynamic endeavor that requires sometimes years of reflection and preparation. I remember reading the book “Code” by Charles Petzold, one of Microsoft’s best programmers to ever serve the company. He said that he has this book “in his mind” for several years before actually writing it. That is just one case in point. For those of you interested in pursuing writing as a career, here are ten steps you can take that potentially could help you toward such a career:

One. Identify and pursue your passion. It doesn’t matter whether it is photography, computers, travel, cooking, or science fiction. Know thyself!

Two. Study to expand your knowledge base. Even though you have identified your passion, it is good to have a broad knowledge base as an individual. You are much more able to socialize with others.

Three. Become inquisitive. The best writers are ones who are always asking questions, and many of them. Imagine yourself as a reporter about your passion and all the questions you wish to ask the lead person in this field or activity.

Four. Network with others. It doesn’t matter whether you open a profile at MySpace, Facebook, or StumbleUpon or even join the local PTA. Get to know people and you will be able to see and experience firsthand the incredible diversity of people that the world has. It is indeed incredible.

Five. Experiment within your passion area. Do you have an idea that has gone unexplored? Do you have questions that nobody can answer within your passion area? Then by all means go for it - and make a discovery that nobody else has - this will boost your self confidence greatly.

Six. Work professionally within your “passion’s” area. If you are crazy about computers, then by all means try to find a job in computers. If your passion is parasailing, then go get a job as a boat captain for parasailing clients at a resort somewhere. Get your hands wet and get to know the professional field of your passion FIRSTHAND.

Seven. Share your passion with others. Perhaps you are at a social gathering or just chatting with friends on the web. By all means share your passion with them, but of course not too much. Tell them about a few “cool” things you have seen or experienced - people always love new and interesting things.

Eight. Brush up on your English or Foreign Language skills. Make sure that you are not totally out of touch with basic grammar rules in the language you hope to use as a writer. This will help you greatly in the writing practice.

Nine. Take a basic writing class if you haven’t already. The purpose of this suggestion is only to help you understand the different formats in which writing can take place, and the kinds of publications that people consume.

Ten. Seek formal employment as a writer in your passion’s field. Now that you have acquired all sorts of great personal experience firsthand, now you can write about it formally. You might need to prepare a small portfolio so that the hiring manager can see that you can write clearly and also you have mastered important concepts within your passion’s field.

Good luck to you

Written by Keith Johnson September 10th, 2008 1 Comment »

Creating great documentation involves more than just typing or writing. It involves a great process of study, reflection and patience. Also, you want to have great tools and resources that will positively affect your work as it unfolds. This list includes ten suggestions that you can apply to your work or consulting location as you tackle your next or even first documentation project.

One. Make sure you have a good computer! I have, at work, an IBM Le Novo laptop and, at home, a HP Pavilion laptop and both machines have served me well. I personally favor HP over IBM, however, the point here is that a good machine with sufficient memory will really make your documentation life easier and eventually more productive.

Two. Install quality software on your machine. Yesterday’s post includes ten great freeware programs you can install, totally free of cost, and that will render you great service in different ways. Some of the applications are designed for graphics, others for text, and others for file transfer and support. I personally favor Microsoft Office 2007, but if you cannot afford this office suite, then by all means install the Open Office suite (see yesterday’s post for a link to this program).

Three. Have a full installation of the product you are about to document on your machine. There is no point in writing documentation about a software program or product that is buggy or outdated for one reason or another. Ask your boss or ask customer service, but get the latest version! You might think I am being a bit overbearing here, but no, I am not. Some companies, upon discovering big bugs, revert to “really old” versions that compiled well, sometimes, and then in future patches or upgrades they try to redo the version that you had on your machine that had all the bugs. Stay informed.

Four. Get the full product specifications before you get started. Yes, there is often a nice GUI in today’s software products, but also there are many things the software can do that only the specifications have (as a source). You will save yourself hours of testing by having an updated copy of the software or product specs.

Five. Get to know the developers and architects. Both the software architects and developers will be able to offer you their personal takes on the program and this will shed light on “why the program is the way it is”. Nobody who writes documentation has a crystal ball (even though some think you do).

Six. Get to know quality assurance and customer service personnel. Why? They are the ones who must work with the final product and sometimes the final product is not the same as the original specifications. Any bugs that are experienced or discovered will be noted by these folks.

Seven. Take good notes as you collect your information. Don’t be afraid to ask questions. Remember, you are writing the user guide or online help! Remember that you are asking questions that users will be asking as they use the program.

Eight. Get managerial feedback as you complete your drafts. Managers in both product development as well as business operations are aware of what investors, customers, and other people are hoping to see in the documentation. They will be both supportive as well as critical. This will help you to refine your text and the document’s overall quality.

Nine. Use Robohelp or Author-It software for your final documentation. Both of these products are designed to help you create professional and user-friendly help files and user documentation. They both rock! A good software company will surely buy its documentation personnel licensed copies of programs like these, because this documentation is going to support the very program the company has developed (the bread and butter of the whole enterprise).

Ten. Get as many people to read and review and comment on your final and published documentation. Be patient and tolerant because not everybody is going to understand your writing the same. Different people will tell you different things. That is alright. Bring these comments to your boss or manager and then take appropriate steps to iron out any “wrinkles” you find, whether they be typos or bad hyperlinks or incorrect information. Soon, your work will approach the 100% level of quality. Now you know how to create great documentation - good luck to you.

Written by Keith Johnson September 9th, 2008 1 Comment »

As a Technical Writer, I have learned to value quality software. And how! In fact, the productivity of a Technical Writer is directly proportional to and dependent upon the quality of the applications that he or she uses. My experience is no exception.

This may sound like a contradiction, but I absolutely love Microsoft products, even though this post features open-source products. Yes, I know, many times Microsoft programs are buggy and also Bill Gates has presented operating system releases and software releases featuring the infamous blue screen. However, over the years, Microsoft has bounced back and really taken its brand seriously and so now many of its programs are awesome.

At the same time, Microsoft products are not cheap and having several or many Microsoft products may be out of one’s business or personal budget. And for this reason I have decided to create this post, featuring what I believe are ten “truly great” freeware programs that you can download from the Internet and are 100% free of cost. Perhaps you might have to register some personal information like your name, address, e-mail and such, however it is well worth it, to get hundreds of dollars of value of not only free software, but quality software as well. Each application or suite listed fulfills a specific computing need, and I’ll make sure I explain this in the list.

(1) Avast Antivirus
This software is really great to defend your PC against all types of malware. It is, in my opinion, as good as Norton Antivirus or other expensive antivirus programs.

(2) Filezilla
If you have a website and enjoying moving files from your desktop or PC to the server with the traditional drag and drop method, this program is for you. They are always updating this program and it is really efficient and user-friendly.

(3) Ultimate Defrag
Every once in a while, it is a good idea to run a quality defrag program on your hard disk. This helps it attain optimal performance and is especially good after you add or delete programs from your computer. It has a really cool GUI that accurately represents the defrag process as it unfolds.

(4) CCleaner
CCleaner simply stands for “computer cleaner”. It does just that - it cleans and deletes all sorts of temporary and “junk” files and items that can be safely removed, without compromising information or program performance. It is easy to use and really keeps your hard drive clean.

(5) Open Office Suite
OK - I know you are calling my a hypocrite here - but wait! Before my current gig, I also was down on change and so used Open Office for a few months, before I was able to buy my own licensed copy of MS Small Business Office 2007. Open Office is always being updated, improved; it is great for students and professionals who are willing to learn its interface. This suite comes with full word processing, spreadsheet, and presentation applications.

(6) Dia
Not only is Microsoft Office semi-expensive, but so is MS-Visio for diagramming and flowcharting. The best freeware option outside of MS-Visio, per the general software market consensus, is a program called DIA. After you download it to your computer, you will see that it runs in two separate windows - one has all the symbols you need for your diagram and the other is the document window. It is pretty cool and I really appreciate this program and what it can do.

(7) Audacity
For those of you who would like to create simple videos or even sound-bytes for presentations or even videos you wish to upload to sites like YouTube, Audacity is your program. It has a very easy user interface and records sound with great quality. You can dub, mix, and do all sorts of cool things with this audio application.

(8) GIMP
For those of you who need to do some graphics work, download GIMP. GIMP is simply awesome and like all these other programs, it is totally free. It has a great palette and you can do many creative and interesting graphic and artistic things. There are also several sites on the Internet that offer free help and support for GIMP users.

(9) Foxit Reader
For those of you who don’t want to be burdened by the Adobe Acrobat Reader, download the FOXIT Reader. It will allow you to view PDF files of all sorts, with great readability and quality.

(10) Comodo Firewall
Need an effective firewall to protect yourself against hackers trying to get into your computer or system? Then download this application and ensure safe computing for yourself. Yes, there are already firewall tweaks within Windows XP and Vista, however this application is a great add-on in any case.

Written by Keith Johnson September 8th, 2008 23 Comments »

The writing experience is one where you need to place yourself in the right frame of mind. If you are mentally upset about something, then it is very difficult to focus and create quality text for your documents - it doesn’t matter whether you are a blogger, writer for an internal corporate newspaper, college journalism major, or other type of writer. You need to be able to sit down and get to work. So, how can this be accomplished? The following is a list of ten tips that have worked for me, and that perhaps can work for you as well:

One. Have a clean desk. On your desk, make sure you have minimal clutter and debris and junk and perhaps once a week you can clean it with some kind of desk-cleaner. I personally enjoy writing at a desk that is clean.

Two. Organize your junk. Writers are notorious for having a cluttered desk with tons of books, papers, or magazine articles stacked or scattered all over the place. Well, I am not against having these items present, but at least organize them so that you can find them when you need them and that you don’t have to waste time searching for **that** book, if you get my drift.

Three. Plants matter. There is nothing more appeasing to the eye than nature. Especially, if you are in an office that has no window, having a plant is aesthetically pleasing to the eye and connects you to nature, even though you are logged into your blog or website and all there is around you is metal and technology.

Four. Water and Tea. Depending upon your personal preference, have close but not too close to your computer or notebook a fresh glass of water or tea so that if you get thirsty, you can take a sip. It is always nice to have a refreshment like this because even though you are only writing or typing, you are still expending “brain” power and the body will soon want its replenishment. Being in a fast paced corporate environment most of the time, I also enjoy a strong cup of coffee in the morning, but don’t overdo the caffeine because if you do, then you might lose focus.

Five. Have a comfortable chair. I am not necessarily advocating for you to get one of those expensive ergonomic chairs, however, a chair that is truly comfortable will definitely help you write with greater efficacy. I have a bad lower disk, so I actually enjoy a wood chair with four legs for support. It doesn’t rock or move, so this stability helps my body relax and helps my mind generate quality content. The choice, of course, about what chair you select, is completely up to you.

Six. Light. As I mentioned above, there are office environments with no visible light or windows to the external world. But, what you can do is buy a small desk lamp with a bit of “character”. So, as you put this lamp on, you will be getting more than light, it’s presence will also help remind you that there is a “light” source next to you besides the, most likely, florescent light tubes above your desk or cubicle.

Seven. Stretch. I personally enjoy standing and going for a brief walk to the water cooler or literally stretching my arms and legs to get my circulation back. Do this, and you’ll feel instantly better. You’ll once again sit to write, and will “keep on going” nicely.

Eight. Humor. I love to get my daily joke in my e-mail inbox. I think humor tempers our lives well and it is also a good remedy against complacency or boredom or your inability to write. So, find a good website on the internet with quality humor, ask to receive this first thing in the morning in your e-mail, and enjoy a good laugh! This will help you immensely.

Nine. Keep conversation to a minimum. It is easy to get caught up in office discussions. However, as a writer, you need to stay focused. So, if someone or a group of people ask your opinion about something but you are in the midst of a great train of thought, just tell them “one moment, please” and that way you keep your “in” with your co-workers or friends but also don’t lose the sacred thought that is going to really make your blog post, research paper, or other document shine.

Ten. Clothing matters. Everybody is different. Some people enjoy “dressing up” and others enjoy “dressing down”. Make it a regular practice to “know thyself” in terms of clothing that allows you to feel relaxed and able to really sit down and write. If you are in a corporate environment, within the rules try to find what works best for you. I personally cannot stand ties. Yes, they look nice, but they also feel like someone is strangling you. So, I cannot write with a tie on my neck. As you dress for maximum relaxation and well-being, this will immediately translate into successful production as you generate and create your documents.

Written by Keith Johnson September 6th, 2008 3 Comments »

If someone asked me “Keith, what is the secret behind your success as a Technical Writer?” I would tell them that there is one class I took when I was in Middle School (6-8 grade in the USA). This class was called “Great Books”. It was a class that focused on short stories of all kinds.

The class would read, daily, a short story and then would discuss the story completely. All characters were analyzed. All situations in the story were analyzed. All places, things, props, conditions, and anything you can think of were also analyzed.

After these items were discussed, the teacher or discussion leader (at one time this was my mom) asked challenging questions to the class and group members, who then engaged in a round-robin type discussion. Whenever a student took a position, he or she had to justify why he or she took such a position. This class was the beginning of my rational and analytical skills that could then be applied in all classes - from science to art history to humanities and foreign languages and philosophy.

So, dear readers, the “secret of my success” as a Technical Writer is simple: the experience of “great books” from my junior high school years. This experience was the foundation builder for all future successes in academics and professional life. Many people say they have good reading and reading comprehension skills, but I believe these skills require constant attention and practice. A good writer needs to be able to read a diverse array of books, internet pages, and more and walk away with a strong understanding of what has been read. At that point, a meaningful review or use of such information can be delivered to the awaiting audience

Written by Keith Johnson September 4th, 2008 Add Comment »

Modern business life entails paperwork, and sometimes “lots of it”. I have worked with different companies that are making good efforts to “go green” and be as efficient as possible, to the point where printing out a document is strictly forbidden. In light of this direction, here are ten suggestions you can take to make sure you are organizing and managing your documents efficiently, so that you can always find them and find what you need.

One.
Create a directory structure that really personifies the complete spectrum of documents.

Two.
Create file names that reflect the true nature of the content in the file.

Three.
Make sure you have an Operating System with a good “file explorer” utility program.

Four.
Make sure you place files in a virtual location accessible to all who need them.

Five.
Make sure these documents are also copied onto a network drive for backup.

Six.
Use a program like “CCleaner” to clean your system and eliminate temporary and useless files.

Seven.
Use a program like “Ultimate Defrag” to optimize the speed of your computer system.

Eight.
Communicate with others about changes you have made to files or the directory structure.

Nine.
Be careful about deleting files without consulting other team members.

Ten.
Work with other team members to make sure maintenance work is done when others are not working with open files or leaving the system vulnerable in any way.

Written by Keith Johnson September 2nd, 2008 Add Comment »

In addition to the Microsoft Manual of Style (3rd Edition) for Technical Publications, I also have on my desk at work the “Handbook of Technical Writing” by Gerald Alred, Charles Brusaw, and Walter Oliu. This book is an excellent source for consultation, especially for grammar and basic English writing-related standards.

Technical Writing is a most unique field because **all** hard and fast grammar rules do not always apply. Technical Writing is a unique combination of **buzzwords** of a designated field along with correct grammar. So, it is sort of a “hybrid-writing” experience, just like you might have a car that has a battery and gas tank (like the Toyota Prius) for power. And so it is with Technical Publications.

These three men have done a tremendous job of assembling important concepts and rules and standards in this book. This manual has an excellent index in addition to an overall well-formed and well-structured contents. So, you can always find what you need. According to the introductory pages of the book, it seems that each co-author has a unique and well-established background befitting for such a great book. Technical Writers depend upon “a few good resources”, if you will, that will ensure the quality of our work.

It is more about writing. It is about interpreting things, presenting them, citing our sources, and things of that nature. Technical Writing is not fiction writing - rather, it requires diligent attention to details and facts and sources. Correctly assembled and synthesized and presenting - the materials gathered can eventually become an informative book, manual, instruction guide, or reference guide. So, today I offer thanks to these great men of the world of Technical Publications for having taken the time to put together this fantastic writing resource.

Here are the major sections of the book:

One. Five Steps to Successful Writing.

Two. Checklist of the Writing Process.

Three. Topical Keys to the Alphabetical Entries.

Four. Topical List of Figures and Model Documents.

Five. Handbook of Technical Writing - Alphabetical Entries.

Written by Keith Johnson August 30th, 2008 Add Comment »