Introduction
Sometimes it may be beyond the budget of a company or individual to hire a professional writer to address their technical documentation. Although in an ideal world all technical documentation must be produced by a highly trained expert, unfortunately we do not live in an ideal. In the same way that many people will try to repair their own appliances, many people will try to write quality technical documents. In the same way that playing with a toaster can cause electrocution, trying to write technical documents from scratch without prior advice will result in failure. As a general rule, you should always look for a specialist, but if for some reason you cannot and you are the unfortunate poor person who has been imposed on documentation, do not despair. This brief guide describes some of the basic skills you will need to contribute to your writing, the technical conventions you should know, the software packages you can consider and the definite things you should avoid. Fortunately, even if you have never written a sentence in your life about something vaguely technical that you will have at least, a broader picture of what technical writing implies.
What is technical writing?
Technical writing, as expected, refers to writing that is technical. Although this may seem a fallacious definition, it is important to remember it. Too many technical authors make the mistake of creating documentation that is too technical or too literary. A good technical author should be able to adjust the balance between the two to fit the end user of the documentation. Technical writing is very similar to fresh, penetrating and yet quite invisible air. In the strange connected world in which we find ourselves, technical writing is everywhere. Software manuals, user guides for appliances, instruction booklets, emails, letters, reports, technical news reports, statistics and biographies in television sports programs, all are examples of technical writing to which people are exposed daily. If you have ever tried to set the time setting on a home video recorder and threw the manual around the room with disgust, you threw a technical writing (although obviously not very good!).
Too many times the technical literature is produced by writers who do not have a sufficiently large understanding of technology, or technologists who lack the ability to write. As a possible technical author, you must follow the very delicate line of having technical knowledge in your specialized field (s), as well as being a & # 39; well & # 39; writer (unlike "bad" writers who can usually be found assaulting sweet old ladies or something). Technical documentation is usually produced for two different user groups, namely expert level users and naive users. As a technical author, one of his first tasks is to classify what audience he is writing for, which leads me skillfully to:
Know your enemy
As the old cliché says, everyone is critical. This is particularly true in the reaction of most healthy people when they face technical writing. As noted in the example of the previous video recorder, technical writing can be impenetrable to the end user. If this is the case, it is because whoever wrote the documentation did not bother to identify their audience and write at their level. It seems an obvious point, but one that is often overlooked, that the user of the documents he is creating, may not really be an expert. Obviously, if you are creating a document in a particular specialized product for a particular advanced user group (a good example could be audit software for computer system administrators), then you will have to write it in a completely different way than if you are creating, for example, a technical manual for mass market computer software aimed at the inexperienced home user. One of the first tasks that you must perform even before putting the pencil on the paper, from the finger to the keyboard, is to identify who will be the user of your documents and build documents addressed to that particular group or target groups. If you get this correct stage, you should avoid having your documents thrown through the rooms with discomfort!
Planning for perfection
Once you have identified the target market for the documents you will create, you should start planning how the documents will be organized. This process depends largely on the documentation that is being produced, but it can follow some general rules. First, if the documents are to support a particularly detailed product (such as a computer application), have your dirty hands as quickly as possible. By examining the product in detail, you can formulate an attack plan and start composing an organizational structure. While exploring the product in detail, take many notes, as doing so during the initial stages of exploration can save you time, which can be absolutely vital if you are working until the deadline. Even at the planning stage, you must ensure that there is consistency in the design and organizational structure of the document. Select numbering conventions, paragraph styles and generate general ideas for design purposes now and save vital time later.
Let in a draft
Before immersing yourself in the creation of documentation, first write each section. This will allow to reorder if the documents that are created do not have a logical flow & # 39; without having a serious impact on the project. Many technical documents (especially for more detailed products) consist of numerous (and in some cases virtually innumerable) iterations. This is because the product changes and changes over time, and one of the main tasks of a technical author is to keep abreast of these changes and ensure that all are well documented. Good technical authors will always pass their documents through as many drafts as humanly possible, refining each draft, until they reach a position where they (and their employer) are convinced that the documentation is timely, accurate and true. Product reflection or process documents.
The devil is in the detail
As already identified, technical writing is called that because it is of a technical nature. Part of being technical is being precise, and part of precision is being as detailed as humanly possible. Even if the documents you are creating are for an advanced and technologically sophisticated user group, your documentation should focus on the details of a process or the use of a product. This can be a difficult feat to accomplish, but not if you write to your audience. Never assume that the reader knows that something about the product or process should be documented, but in the case of advanced users / experts, at least they have the common sense to recognize the fact that they probably do not need to be told how to use the equipment that operate daily. When describing how to carry out a particular activity or task, identify each stage involved (list them if this conforms to the conventions of the type of document you are creating) and to ensure the accuracy of what you have written, try it yourself, or Even better, rope in a volunteer of the same skill level as the end user.
Choose the right tool for the job
Although it is possible to create technical documents with parchment and blood, it is not advisable. There are many specialized software applications to help you create powerful documentation, and part of your duties as a technical author include the selection of the right tool for the job. To a large extent, this depends on the nature of the documents that are produced and the nature of their final distribution. If documents can be delivered over the Internet, this is undoubtedly a way to consider. To do this, use packages such as Flash MX and Dreamweaver to achieve this goal. To get integrated online help, you may want to create plain HTML documents or, alternatively, select a specialized package such as RoboHelp or similar. In the case of print-based documents, you must select a software package powerful enough to handle what you throw.
Many inexperienced technical authors instantly turn to Microsoft Word (since it is ubiquitous in many commercial and private environments). Unless your documentation is less than 150 pages and you know how to create templates and make macros, avoid MS Word. As any technical author will tell you that you have unpleasant habits and that it can often be an unstable package to work with. If you are creating documentation with many graphics, you may want to consider Quark Xpress, or potentially choose the industry leader in the field, Adobe Framemaker. Regardless of the software you select, you must ensure that you become incredibly competent with it, either by investing in training or using it day after day.
Communicate: that's what you get paid to do!
Many people will tell you that creating technical documentation is tedious and repetitive. These people are wrong, and possibly also morons. Although you can find the process of creating technical documentation & # 39; boring & # 39; (If you do, you are at the wrong job!) It is not. Creating quality technical documents is a vital stage to allow people to use technology properly and correctly. Although no user will approach the documentation they create in the same way that they approach a novel, it can ultimately help them achieve what they want to achieve with technology. No matter how & # 39; boring & # 39; It may seem that the process is, allowing users to achieve their goals by reading their documents, which will give them pride and, in fact, happiness. As long as you remember the positive effects that technology can have on people's lives, when you create your documents you can communicate more effectively, as you will be happier in the communication process. Throughout the documentation life cycle, you should try to communicate with your colleagues as often as possible (if applicable). Let them read your documents, listen to their criticisms and adjust their documents (if you can't discuss your corner!). A technical author is paid to communicate, make sure he does, and never forget why he is communicating, and to whom, in the documents themselves.
Common mistakes to avoid committing
When creating technical documents, there are a number of fatal failures you can make. Although it is by no means exhaustive, this section details some of the most common mistakes made by the new authors, with the hope that you also avoid making them:
Be condescending: although the technical documentation must be clear, it must never be condescending. He is not creating documents for morons to read, but consumers and customers. You should always write at the level of your audience's skills, but no matter what technical level people are in, they are not stupid. Even children are offended when they are condescending, do not make that mistake with someone who is paying their salary, child or otherwise.
Excessive use of humor: people do not read technical documents to entertain themselves, they read them in the hope of successfully completing a process or extracting information. Unless it is relevant to the end user, avoid humor whenever possible. If you are writing a book, good and good. If you are writing a manual, avoid humor like the plague, as most of the time users will miss the joke and simply hate the condescending idiot who wrote the documentation.
Inconsistency: even at the drafting stage, you must ensure that all the elements used in your document are consistent. This applies to both & # 39; tone & # 39; of the document regarding its design. Be sure to use consistent senses (first person, etc.), as well as page layout, paging elements, headers and footers, and all other textual elements.
Reading test: at the end of the creation of a technical documentation, you will probably get tired of seeing it. It does not matter. What matters is what comes out of your office or home, it is accurate. To that end, read the document in all its drafts, and before distributing it, read it over and over again. Never trust spell checkers (they never work) and if you can avoid it, never rely solely on your own criteria. Have your document read by as many pairs of eyes as possible before distribution, after all, they could detect the only thing that has been lost during the entire creation process.
Sassy Conclusion / Self Promotion
Technical writing is not, regardless of what you may think, an easy job. It requires experience, patience and a very strange mix of skills. Like any other job, you can learn how to do it, but even that tuition will not necessarily make you good at it. To be a good technical author, you must be anal but creative, focused but communicative and a flexible expert. This, as you can probably imagine, is not a simple task. Although you may think that creating technical documents is easy, creating accurate, consistent and timely documentation with a high commercial standard is a very challenging role. Regardless of your budget, you will eventually provide a meaningful ROI if you hire a specialist. After all, they will be able to do in days, whatever breaks your hair if we try to achieve it in weeks, if not months.
If you essential to savor the Opportune Beingness: Making money in the relieve of your own lodging authorship online, then this is for YOU!: Click Here
Comentarios
Publicar un comentario