Intro to Technical Writing

Technical writing is a different kind of writing. As a matter of fact, it is a very different kind of writing. It is different from fiction, which primarily focuses on entertaining the reader with intriguing stories and absorbing plots. It is different from non-fiction, which seeks to both entertain and educate by employing fact-based narratives. But unlike fiction and non-fiction, technical writing is never read for enjoyment.

Technical writing has the twin goals of education and instruction.  Good technical writing is often dry and boring, but must always be extremely detailed. It is also directed toward a more limited audience than fiction or non-fiction. Apart from such items as an auto repair manual, which might be targeted at all Ford mechanics, most technical writing is seldom read by more than a handful of individuals. Additionally, this type of writing spans many disciplines, from how to assemble a jet engine to provide new functionality to an existing computer application. But no matter how disparate the fields of concern may be, all share certain characteristics. It is those common features I want to highlight in this blog

The first document I will address is the Requirements Document. All the technical writing which I authored was sourced from a requirements document. It was my roadmap and guidepost. Without a requirements document I could not begin my design work, and without a good one I would never finish it. In my work environment, the requirements were historically gathered and formalized by a business analyst. This individual would have subject matter knowledge of that part of the business being impacted by whatever change sought within the system. Currently, most IT shops are moving toward the ‘agile’ methodology for project management, with requirements gathering a critical component of that approach. Agile is basically an iterative process with teams of people working in a dynamic manner simultaneously to accomplish desired goals. The methodology prior to agile was termed ‘waterfall’, meaning the project moved along in a purely sequential manner, somewhat analogous to an automobile being built on an assembly line. Regardless of which style is followed the results should be the same, a requirements document as complete as possible. At a bare minimum, every document should have the following sections:

Project Description––In a general sense, describe what the effort is about, such as ‘Add department manager name to gross sales report’.

Functional Requirements––In detail describe what action is being requested, such as ‘in last column of current gross sales report add department manager name in format of first name initial followed by first 20 positions of last name, i,e, T.Smith. If job position is vacant, print ‘Open Position’  in last name field of report.’ It is critically important that each requirement be given a unique tag to enable traceability to the design document.

Constraints––Any issues that may impair the successful completion of project, such as ‘project needs to be completed by year-end processing’. This constraint could cause the expenditure of additional resources on the project to meet target date. It could also cause the scope of the project to be reduced by eliminating some the requirement to meet the desired timeline.

Testing Requirements––Any special concerns around testing, such as ‘newly created file needs to be input into application XYZ for it’s system testing’.

While these requirements are IT specific, other types of work efforts would have their own distinct needs that must be adopted into this format.

The instrument which takes those requirements recorded in the requirements document and translates them into a written description of the process where they become fully actualized is the Detail Design Document. This document will provide all necessary guidance and instruction to an individual or team as to how to accomplish the project goal laid out in the requirements. Often the developer who writes this document is the same one who performs the coding work, but this is not always the case. Most of the design documents I wrote were for my own use as the developer. I was told by management, however, that the document should be detailed enough so that ‘if I was hit by a bus leaving the building someone else could take over for me and complete the project’. With the increasing amount of coding work being performed by outsourcers, this type of expectation is more of a demand than a request.

The Detail Design Document will typically have, at a minimum, some form of the following sections  (the section naming conventions will vary):

Project Description––A general explanation of the objective of the project and how that objective will be achieved. It should include such items as the business need, scope of the project, customers (now referred to as ‘stakeholders’), and the components of the application being impacted by the change. Keep in mind that management often refers to this document for their status reporting so a summary section should be created if the description contains a lot of ‘buzzwords’ and detail not familiar to higher levels

System Implications––This section will describe how the change requests will impact the system. If, for instance, a new program is required, the language of the code would be noted here. If a new VSAM file is constructed which must be connected to a CICS region, that also would be documented here.

Construction steps––This area is the focus of the document. it will, in detail, describe the logic needed to satisfy a functional requirement found in the requirements document. If the change is to a Cobol application, the program name, affected paragraphs, and all needed logic would be listed here. Each step must be mapped to the requirement it is addressing.

Test Plan––The unit and test plans will be documented here.

Constraints––Any issues uncovered during the construction phrase that could impact the target date are located here.

While there is much more to technical writing than what I have addressed here, this is a good place to start for someone unfamiliar with the process.