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?