Rules in Technical Documentation

Writing style of documentation can vary, depending on the product, and its target audience.

General English
General English follows standard grammatical conventions. Sentence length varies, but seldom are sentences longer than 25 words. Most sentences are simple or compound. Complex and compound-complex sentences appear infrequently. The vocabulary favors common straightforward words rather than more obscure words or nominalizations.

Formal English
Formal English uses more long complex sentences and complete grammatical constructions. Passive voice appears often, as do technical terms and nominalizations. Formal English may be appropriate for some technical material, but if the same sense can be conveyed by simpler general English, it should be. Sometimes a writer can lose track of correct grammar (say of subject-verb agreement) in convoluted formal English sentences.

Informal English
Informal English is breezy and journalistic. It's marked by short sentences, contractions, and directly addressing the user. Some grammatical constructions may not be complete. Informal English may be appropriate for some consumer products, but some attempts to be friendly can sound condescending.

Jargon
Jargon is a neutral term — it refers only to the technical language used by some particular profession or other group. It can be acceptable in the right context for a particular audience, where it serves as a shortcut to understanding concepts for those who understand the term.

Technical jargon is often acceptable in documentation for programmers and other technical audiences where you can assume a certain background or level of expertise. Marketing jargon and buzzwords generally are not acceptable. You can find a list of jargon in the index. Some of the terms are acceptable, especially in certain circumstances, and some are not.

Technical Writing

What is Technical Writing?
Technical writing, a subset of technical communication,is used in fields as diverse as computer hardware and software, chemistry, the aerospace industry, robotics, finance, consumer electronics, and biotechnology. Technical communications are created and distributed by most employees in service organizations today, especially by professional staff and management. Writing well is difficult and time-consuming, and writing in a technical way and about technical subjects compounds the difficulties. To be useful, information must be understood and acted upon.

Fortunately, tools and techniques are available to make writing more accessible and easy to understand.

Tools used in technical writing
Writing , editing, and design skills form the foundation of technical writing. But these skills only get you started. You need to know how to use publishing programs, help authoring tools, web design, and graphics packages. Though technical writers write online help systems, design web sites, and deliver multimedia training publishing programs are the basic tools of the industry.

Technical Writing tools are categories in four types:

1. Publishing tools: Technical writer should understand how to use features of tools e.g., format, graphics, macros, indexing, style, conditional text etc. Publishing tools are FrameMaker, MS Word, QuarkXpress, Interleaf, Arbortext, PageMaker, InDesign etc. FrameMaker and MS word are the most requested tools in industry.

2. Help Tools: It is generally use for web based and desktop application. The Help tools are RoboHelp, Doc to Help, Flare, ForeHelp etc, but RoboHelp is the most requested tool in software industry. RoboHelp is consisted with variuous outputs format such WebHelp, JavaHelp, OracleHelp.

3. Graphics Tools: Technical Writer should not be professional graphic artists. Technical writer should be basic knowledge of graphics. Graphic tools are Photoshop, Illustrator, CorelDraw, Paint Shop Pro etc. These tools use for edit an image/ picture for use in manual or online Help.

4. Web Tools: Technical writer need to know HTML that is the programming language used to create documents on World Wide Web and it comes in flavors at the moment. Web tools are FrontPage, Home Site, Cold Fusion and DreamWeaver etc. FrontPage and DreamWeaver is the most requested programs and both are alternative to each others.

There are few jobs for people who do not have an expert understanding of at least one or more of these programs.

FrameMaker

Adobe FrameMaker is the most requested tool in this industry. If you don't know it—you need to buy it or really work with the demo. The Windows academic version is relatively cheap.



RoboHelp

Adobe RoboHelp software provides a fast and easy way for technical technical writer and communicators to build, manage, and publish professional online help systems and knowledge bases.







Microsoft Help Workshop
Help Workshop is a program that you use to create Help (.hlp) files, edit project and contents files, and test and report on help files. Help Workshop takes the information in the project (.hpj) file to combine the topic (.rtf) files, bitmaps, and other sources into one Help file that can be viewed using the Microsoft Windows Help program.

QuarkXpress
Used in creating magazines, newspapers, catalogs and similar printed materials.


Adobe InDesign
InDesign is a professional design and layout tool for producing high quality for both print and on-screen delivery.


Free Help Authoring Tools

Job Profile of technical writer
Perform document coordinator/editing and writing functions, including editing for proper use of grammar, punctuation, consistency of style and format, and adherence to established standards/procedures. Must have experience on technical projects. Knowledge of using style manuals to determine form and style of technical documentation. Ability to understand and work in Documentum effectively. Create UserManual, Troubleshooting, Release Note, Create Help file & presentation, etc.


Certification
http://education-portal.com/technical_writing_certification.html


Web Links:
http://www.klariti.com/technical-writing/index.shtml
http://www.io.com/~hcexres/textbook/

Books:

• Technical Writing 101: A Real-World Guide to Planning and Writing Technical Documentation, Second Edition by Alan S. Pringle and Sarah S. O'Keefe
• Handbook of Technical Writing, Eighth Edition (Handbook of Technical Writing Practices)
• Technical Writing: Process and Product (5th Edition) by Sharon Gerson and Steven Gerson
• Technical Writing: Principles, Strategies, and Readings (6th Edition) by Diana C. Reep
• Technical Writing for Dummies by Sheryl Lindsell-Roberts