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