Document Development Life Cycle (DDLC)

The Document Development Life Cycle (DDLC) is a sequential collection of various phases that are used by a technical writer to create a well structured and information rich technical document.

The DDLC comprises of the following stages:



Phase 1 => Requirement Analysis
Requirement Analysis is an important phase of the Document Development Life Cycle. In this phase the technical writer gathers the useful material for the project and understands and analyzes all the information of the project. He/ She analyze the project requirement, audience level, and tools that will be used in the project.  The project requirement helps to know about the type and use of the technical document. The audience level informs a technical writer about the reader level i.e. who will be the reader of the document. On the basis of the reader level complexity of the document is decided.

Technical writer must study the software from the technical point of view. He / She must use and test the software product in various ways to get the detailed idea about it. He /She should then list down all the queries and problems faced while studying the product. And before meeting and interviewing the important people, the technical writer must do his homework and prepare a questionnaire related to the project. He / She may have to meet the people many number of times to completely understand the project. At the end of this phase technical writer must have resolved all the problems and queries in terms of understanding the documentation.

Phase 2 => Designing
This phase includes the content collection and content representation that is how the content should be represented, what should be the format to represent the content, what should be page numbers for the required document, projects completion date, and so on. A technical writer has many sources to collect the content, such as his/her knowledge about the technology, audience research, Subject Matter Expert (SME), and Internet. The best source for a technical writer to collect the information is Internet and SME. Therefore, a technical writer must have good idea about the project requirement to use these resources. A good bunch of information helps a technical writer to prepare good, concise, and information rich document on the projected time.

Phase 3 => Developing
This phase the actual content is scripted on the basis of the project design, which has been created in the preceding phase. The required illustrations and graphics are also prepared and inserted in the document.

Phase 4 => Testing
This phase of DDLC involves measuring the quality of the document. A technical writer reads the scripted document to find and correct the spelling errors and maintain the data
consistency.

Phase 5 => Publishing
After fixing the all the bugs found during the testing phase, now the document is ready for publishing.

Phase 6 => Maintenance 
In this phase, technical writer backup the entire document for future use, like add the file to Configuration Management Tool (IBM Clear Case / Microsoft Visual SourceSafe).

Help Authoring Tools in Technical Communication

Technical Writers use help authoring tools for creating online help (application help). There are lots of help authoring tools in market. You can also find some few free tools like HelpMaker etc.

Top 3 Help authoring tool:
1) Adobe RoboHelp

Help authoring tool product from Adobe Company. RoboHelp is a commonly used application to create Help systems, Help for the Web, and user manuals. RoboHelp enables user you to create projects for:

• WinHelp - .hlp format
• Microsoft® HTML Help - .chm format
• WebHelp - designed for Web application (HTML format).
• JavaHelp - Sun Microsystems' standard for providing user assistance and electronic documentation for Java applets and applications.
• Printable format (PDF).

For more information and demo check Adobe official website.

2) Author-it
A product from AuthorIT Company, established in 1996. Basically Author-it intended for creating, maintaining, and distributing content.

Company quotes:
"The Author-it suite is based on the philosophy of One Source, One Solution. This means that once content is created, the information can be easily shared across multiple documents and published to a wide range of different print, help, and web formats."


Author-it can produce documentation in the following formats:

• RTF, PDF, or Microsoft Word format for printed documentation
• Microsoft WinHelp (Windows Help)
• Microsoft HTML Help
• Web and browser based help
• XML
• DITA (Darwin Information Typing Architecture)

For more information and demo check AuthorIT official website.

3) MadCap Flare

A product from MadCap Software, company was formed by software engineers who came from Adobe Systems and Macromedia. Flare is a powerful, XML-based professional content authoring and publishing software application.



Flare can produce different types of outputs like:

• WebHelp and  DotNet Help 
• PDF, XPS, and Word
• Microsoft Compiled HTML Help

For more information and demo check MadCap software official website.

Documentation Quality Checklist

When reviewing Technical documentation, online help written by yourself or by a colleague, it is especially difficult to maintain an objective, unbiased view.

The following checklist aims to help you bear in mind the key factors.


Goal-oriented approach 

Most of the time end user read technical documentation or online help is when they have been stuck with a task. Therefore, they will be looking for a description of exactly that task in the documentation.

• Does the documentation structure reflect the technical architecture of the product (= poor) or does the documentation reflect the goals and tasks of the user (= good)?
• Does the documentation tell what you want to say (= poor) or does it tell what the user wants to know (= good)?
• Does the documentation describe what the user can see (= poor) or what he or she cannot see (= good)? Does the documentation describe the product (= bad) or its use (= good)?

Clarity

• Is the structure simple and clear? Or are there chapters, subchapters, subsubchapters, subsub-subchapters, ...?
• Does the sequence of chapters reflect the frequency of use? Do the more important topics come before the less important ones? Do the general topics come before special issues?

Direct access

• Is the text clearly structured with subtitles? Or are there many long, verbose, crowded texts?
• Does every paragraph focus on one topic only, or is the information mixed up?
• Are instructions clearly numbered step-by-step?
• Can the user select what he or she wants to read in a specific situation: concepts, procedures, or parameter details? Or are information types mixed so that the user always must read everything?

Navigation and search

• Is there a clear, user-friendly navigational concept, or are there just links "from everywhere to everywhere"?
• Is there a manually authored index or is there just an automatically generated index?
• Does the index contain synonyms? (Example: Would you find a topic named "Vehicles" also if you were searching for "car", "truck" or "motorcycle"?)
• Is the index a multilevel index and are all index terms unique? Or are there terms that point to more than one topic, leaving the user with the trouble to choose?

Tone, unambiguousness

• Does the text convey confidence and a sense of security, or is it rather intimidating?
• Are there clear instructions that address the user directly (example: "Click ... to ...") or does it remain unclear who must act: the human or the machine (example: " ... must be carried out")?
• Are there any phrases that leave open whether the user must act (required action) or may act (optional action). (Examples: "You should ...", "It might be necessary to ...")?
• Do all titles tell in advance what will be covered within a topic or chapter? Or does the user have to guess and read the first paragraphs just to find out that this is the wrong topic. (Typical examples of this are topics with he heading "Overview". Nobody can tell what these topics are about before reading.)
• The rules for titles also apply to link titles in online help. Are they clear enough to tell where a link will take the user? Can the user assess whether it is worth the click before he or she leaves the topic?

Consistency, terminology

• Do all documentation components of a product line follow a common concept, or does the user have to get used to different documentation all the time?
• Are technical terms used consistently, or are there several names for the same thing?
• Do the terms used in the documentation match the terms used on the device / within the software?

Structure in detail

• Do the structure and the writing style make it easy to find and to comprehend the provided information? Is it possible to access single parts of information selectively?
• Do the most important things come first?
• Does the information that every user will need come before the information only some users will need?
• Does the most frequently needed information come before the information that is only occasionally needed?
• Does the general information come before the specific information?
• Do things that belong together stand together?
• Are the keywords at the beginning of the sentences?
• Are sentences short and simple? Can they be understood also by nonnative speakers?
• Is there only one piece of information per sentence?
• Are there any empty phrases and filling words that could be left out?

Layout

• Does the layout look professional and functional? Or is it rather colorful and crowded, and takes off attention from the content?
• Does the layout support scanning and skipping?
• Does an online document use fonts that are suitable for on-screen reading (non-serif fonts)?
• Does an online document reserve the underline attribute exclusively for hyperlinks? Can the user immediately see what is clickable and what is not?

Authoring process, updates and translations

• Are the documents generated with the help of a suitable authoring system, or are things fiddled manually? Can the documentation be updated and reproduced with little effort? For example, have there been set up any page break rules within the authoring system? Or will the layout have to be redone manually after each update and translation?
• Are both the authoring system and the file formats ready for the future?
• Are the texts written in a translation-friendly way?
• Do file formats, authoring system, and document structure support single sourcing, so that additional formats, media, and versions can be produced from the same source?

Use of specific media features

• How close and how efficient is the integration of online documentation with the software? Can the user just open a PDF? Or is there some sort of context sensitive or even embedded online help?
• Is the online documentation just an on-screen manual or does it make use of the great possibilities online media provide: interaction, animation, and personalization?

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