ABC's technical writing and its meaning? definitions and examples

by Guest12835402  |  9 years, 10 month(s) ago

4 LIKES UnLike

definitions and examples

 Tags: abcs, Meaning, Technical, writing



  1. Guest23615255

    i need the abc's of technical writing pls.. from a to z.. tnx

  2. Guest15486122
    what is normal procedure in technical writing
  3. Guest13652784
    ABC's technical writing and it's meaning?
  4. Guest12920946
    accurate bold concise
  5. Ali Abdullah
    Hi, Writers are now and then called upon to create technical documentation. This is a good source for additional income. The majority can do it, for sure, but for those who are unsure there are certain guidelines for technical writing that must be followed to create clear and practical documents. This overview addresses a few of the basics of working as a technical writer by examining common elements, and then describing how to improve upon them. Some of the elements to consider are: knowing the reader first; knowing the final product or medium; setting the attitude and approach taken; the writing style, choice of words, and clarity; knowing the technical level of the copy; and finally, developing the format for the documentation. This overview is not intended to be an instructional manual because it will only scratch the surface of the craft; it is meant to be a high-level guideline for first-time or once-in-a-while technical writers. Know the Reader First, it should be known if the reader, or end user, is a professional who will be fundamentally familiar with the subject of the document, that is, an engineer, manager, technician, student, or a high-end user, or a non-professional or someone reading for information only. This factor must be determined before the writing begins, to settle on the technical depth, word choices, and attitude of the writing. It is also necessary so information is not written down to the professional or over the head of the layperson. The end task for the reader is important. Is it for information only, building or using a product, learning a process, testing or validating a process or application, examining complicated details or figures, using an application or process, or maintenance or repair? And, is this document part of an overall document set? In knowing the end task for the reader, the information can be presented and detailed accordingly by the writer. Know the Medium and the Final Product Some of the final products of technical writing are standard documentation, such as user guides, software manuals, hardware manuals, maintenance and repair manuals, testing guides, training material, and many others. Also, the writer may be asked to write for web content or design, computer-based training, online help systems, or marketing material for sales, to name a few. Each of these final products has its own conventions and limitations that the writer must be aware of before starting the assignment. When starting a new assignment, most writers are baffled by the definitions, word usage, and acronyms used by the developers or engineers. Starting a definitions and acronyms list for personal understanding is a good start and more than likely it will be used in the documentation as well. Standard documentation is the most common final product and involves writing detail and explanation, including graphics and references. This usually includes complicated details and the most important focus for the writer is to keep these details well organized. Keeping common chunks of information grouped together and in the proper order keeps the reader involved and better informed. Web content must be brief, direct, and to the point with a minimum of words because it is viewed in a limited screen area. Much like advertising copy, the web page must sell itself at the first glance or the readers will jump to the next page at the click of a mouse. Online help systems are a combination of web page and standard documentation copy. There is normally a great deal of detail, but it must be in brief and focused chunks. Each statement or paragraph must stand on its own because the normal process of moving from link to link in a help file will force the user's detachment from the previous paragraph; thus, it must speak for itself. Marketing material for high-tech products must be a combination of all of the above with the overriding aura of a sales pitch tying it all together. Photos and graphics are usually used in marketing materials. Write the copy so it stands on its own. Do not describe the colors because they are in the photo; do not go over the numbers because they are in the graph; explain why the colors and numbers should be on the reader's desk or in her business. Attitude and Approach It is best to work with the reader, not against the reader. The quicker the reader comprehends the documentation, the more effective it is. Write specific rather than general information. Technical readers are usually interested in details, such as facts, figures, conclusions, recommendations, and especially how to do it. The key here is to make it clear and to the point. Too many facts and figures within a paragraph can lose clarity, but placed in a table or a bullet list, they become easier to read. Even listing them within a paragraph by (1) numbering the separate items, (2) putting the numbers in parentheses to separate them and make them easier to remember, and (3) putting them in a logical sequence, is a common approach. Recommendations and how-to-do-it copy can be easier to follow if it is in numbered or bulleted lists. Sometimes using a check-box square in place of a number or a bullet can give the impression that each step should be read and checked off, even if only mentally by the reader. Style Write in a clear style, not chatty as in a personal letter, but simple, direct, expressing the point, and relaxed yet professional. Use the active voice rather than the passive voice. Action must be expressed directly rather than indirectly. "Do the act" rather than "the act was done." Example: "Pat tested the program," rather than "The program was tested by Pat." Word Choice Use jargon (the technical terminology or characteristic idiom of a special activity or group) sparingly. Technical terms and words are helpful shorthand when addressing the documentation to readers within the profession, but may confuse readers without that special background. The word "yield" can mean "the amount or quantity produced" to an engineer, but "slow down" to the driver of a vehicle. Use legitimate technical terms when they communicate the meaning and ideas clearly, but not because they sound impressive. Avoid important-sounding words if simple words that mean the same thing exist. In other words, speak plain English. If jargon and those rare words must be used, consider a footnote or glossary of terms (or even a brief definition in parentheses) to keep the reader from diving for the dictionary every few minutes. This also helps the reader keep focus on the subject. Clarity As stated above it is best to write to the point and communicate the information in as few words as possible. Do not take up too much of the reader's time and avoid redundancies or wordiness. In other words, say it once, and clearly. Be consistent in style in the use of numbers, hyphens, units of measure, punctuation, equations, grammar, symbols, capitalization, technical terms, acronyms, and abbreviations. This creates a comfortable zone for the reader and avoids confusion. Define acronyms after the first use or as soon as possible in the document (or for larger documents define it again in following sections). Do not assume the reader will know what is meant. If the definition of a word or terminology could possibly be unclear, define it in an index, footnote, or in parentheses. Certain sections of larger documents are often separated for use in other documentation, so the definitions should be carried with it. Technical Depth The technical depth is directly related to the point of view of the reader. Know the reader and write to that depth. Everything that is available on the subject should be covered in the document, or referenced to another available source. A bibliography or index can help here. A separate section with a list of special definitions and acronyms within the document is a big help. Format Break the writing into short sections and paragraphs for easier reading. Creating an outline is a great start because it can directly reflect the headings and sub-headings in the order the information is being presented. If you are working with separate special material experts (SMEs) for each section, they can be assigned by heading for their input. In the same way, short sentences are easier to read and hold the readers attention rather than long, drawn-out, wordy, overly comma-separated, strings of words like this one. Using visuals, (drawings, photographs, maps, graphs, pie charts, bar charts, tables, and schematic diagrams) reinforce the text and make technical communication more effective. This is an area a writer must approach by either learning to use some basic graphics programs, or working with a graphic artist. Generally it is more efficient for the writer to create the graphics rather than the time consuming process of coordinating it with another person. Review, Review, Review Peer review is one of the most important processes. Everyone who has contributed input must review the documentation, or at least the section or information he has contributed. All changes should be reviewed. Management review usually comes after the document is finished and they must add their signature of approval; they will not if the document is not correct. The technical writing process is a simple expansion of common writing and editing practices combined with organization and research. Working with others, especially an editor or another writer, is a plus for improved accuracy. Developing and maintaining certain standards and definitions at the beginning of a document creates consistency. Creating an outline or even a flowchart for the procedure or information helps the writer organize unfamiliar material. Charts and tables developed before writing can help with researching the required information. Starting with a pre-defined document template or style sheet makes it easier to organize and format the information. Keeping it simple and preplanning are the keys to successful technical writing.

Question Stats

Latest activity: 8 years, 3 month(s) ago.
This question has been viewed 5932 times and has 5 answers.

3 People are following this question



Share your knowledge and help people by answering questions.