Technical Writing
Technical writing, a form of technical communication, is a style of writing used in fields as diverse as computer hardware and software, engineering, chemistry, the aerospace industry, robotics, finance, consumer electronics, and biotechnology. Technical writers begin by forming a clear understanding of the purpose of the document they will create.
Technical writing comprises of DDLC (Document Development Life Cycle). Before learning about DDLC, let us know what is Software Development Life Cycle and how is it related to DDLC and Technical writing.
Software Development Life Cycle
SDLC (Software Development Life Cycle) is the process of developing software through business needs, analysis, design, implementation and maintenance. Software has to go through various phases before it is born which are as follows:
(i)Generating a Concept – A concept comes from the users of the software. For example, a Pizza Hut may need software to sell pizza.
An Indian store may need software to sell its newly arrived movies or grocery. The owner of the company feels that he needs software that would help him in tracking his expenses and income as well as enhance the selling process. This is how the concept is generated. The owner will specifically tell the software company what kind of software he would need. In other words, he will specify his requirements.
(ii) Requirements analysis – After the owner (user) knows his requirements, then it is given to a software team (company) who will analyze the requirement and prepare requirement document that will explain every functionality that are needed by the owner. The requirement document will be the main document for developers, testers and database administrators. In other words, this is the main document that will be referred by everyone. After the requirement documents, other detailed documents many be needed. For example, the architectural design which is a blueprint for the design with the necessary specifications for the hardware, software, people and data resources.
(iii) Development: After the detailed requirement documents (some companies have design documents instead of requirement documents), the developers start writing their code (program) for their modules. On the other hand, the testers in the QA (Quality Assurance) Department start writing Test Plans (one module=1 test plan), test cases and get ready for testing.
(iv) Testing: Once the code (programs) are ready, they are compiled together and to make a build. This build is now tested by the software testers (QA Testers)
(v) Production: After testing, the application (software) goes into production (meaning, it will be handed over to the owner).
(vi) End: And one day, the owner will have say bye to the software either because the business grows and this software does not meet the demand or for some reason, the he does not need the software. That’s the end of it.
Fig: SDLC
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. To achieve success in the field of technical writing, one should have conceptual knowledge of DDLC. Various phases of DDLC are:
Project Analysis
It is the first phase of DDLC in which a technical writer 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. For example, if the reader level is beginner or beginner to intermediate then the document will be scripted in a very simple language including lots of illustrations. But if the audience level is intermediate, intermediate to advance, or advance then the language can be flowery. The tools are decided on the basis of the project type. For example, if the document is an online user guide then RoboHelp should be used while in case of user manual MS-Word is used.
Project 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.
Developing the Content
In this phase of DDLC, 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.
Editing the Content
This phase of DDLC includes the document’s editing, which is done on the basis of the format designed/selected in the project designing phase.
Proof-Reading the Content
In this phase of DDLC, a technical writer reads the scripted document to find and correct the spelling errors and maintain the data consistency.
Content Maintenance
In this phase, a backup of the document is taken for future use.
Fig: DDLC
Relation between SDLC and DDLC
Although there are many steps in SDLC, this article lists out only the important stages of SDLC. They are
1. Requirement Gathering
2. Analysis & Design
3. Coding
4. Code Review & Testing Phase
5. Launch (Alpha & Beta releases)
6. Maintenance
Every software project has its own customized SDLC framework.
All the proprietary framework versions are dependent upon the skeleton structure of the above SDLC framework.
Just like how every software project is dependent on SDLC, in the same way, every documentation project also is dependent on Document Development Life Cycle (DDLC). The DDLC framework is divided into the following steps.
1. Understand Product/project requirements
2. Doing Audience Analysis
3. Deciding about Output formats (.PDF, Online Help) & Documentation deliverables
4. Zeroing on Documentation & Graphic tools
5. Gathering the base or source documents
6. Template Designing
7. Time frame & Estimate
8. Identifying Subject Matter Experts (SMEs) & points of contact
9. Identifying peer, technical, and editorial reviewers
10. Creating the Documentation Plan
11. Draft Table of Contents (TOC)
12. Doing Content Development
13. Managing Review Cycles
14. Incorporating Review Comments
15. Final Output
All the preceding DDLC framework steps can be summarized into five subcategories, which in turn can be mapped to every step of SDLC. The five summarized subcategories are
1. Preparation of the Documentation Plan
2. Writing the content
3. Reviewing the content
4. Document Delivery
5. Document Maintenance
Since every Documentation project in software field depends upon the corresponding project/product, the SDLC framework of the same has to be mapped with the DDLC of the corresponding Documentation project.
Mapping of SDLC vs. DDLC
1. Analysis & Design Preparation of Documentation Plan
2. Coding Writing the content
3. Code Review & Testing Phase Review the content
4. Launch (Alpha & Beta releases) Document release
5. Maintenance Document maintenance (incorporating functionality enhancements & modifications)
As you can see from the preceding mapping, every process in SDLC is mapped with the corresponding process in DDLC. Most of the companies, particularly product companies, want the documentation ready by the time the product hits the market.
For the companies following Agile methodology, when the product is under development stage, there will be frequent enhancements, corrections, etc, during each iteration. Just like how the changes are incorporated in the code, in the same way, changes have to be done to the corresponding documentation to keep the deliverables up-to-date as per the client/market requirements.
