Software Documentation and Software Processes
One of the more difficult tasks for all Technical Writers is the design and development of software documentation; however, technical writing for the software industry is no longer just writing documentation. To be successful, the Technical Writer must be able to adjust quickly to a fast-paced environment and be well versed in:
- Software Development Life-Cycle
- Requirements Analysis, Functional Specification, etc.
- Software Testing and Quality Analysis (QA),
- Software Configuration Management (SCM),
- Interpersonal Skills,
- Process Management, and
- Project Management.
Many software development concepts taught are for the "perfect" software company---a company with design documentation and available information and processes to support the Technical Writer's work. Real-world technical writing is not straightforward and does present challenges beyond the Technical Writer's expectations.
For instance, with most software companies, time to market is incredibly important. In most cases, one person devises an idea and starts developing a product. From the prototype comes a business plan to acquire venture capital. Finally, a new company with several employees is born. The problem is that, in all of this, no one bothered to document what it is that the product does or how it is designed ... it sits in the mind of one person.
To alleviate this problem, it is essential that a Technical Writer be knowledgeable of the various aspects of software development, testing, and configuration so that they know where and how to acquire the information that they need. Of course, it is not a simple task because many software companies do not have solid processes for each step of the development cycle, which adds confusion to the documentation process. Once frustration sets in, it is nearly impossible to acquire any information because many of the developers will merely put the writer off. What does one do?
--- Watch me pull a rabbit out of my hat! ---
You have to come up with some process that you can use to manage the project's design and development information. It is important to understand "a process" for developing software documentation as well as managing software projects. You become an information architect and a project manager!
One process I pulled from my Software Engineering days follows a "waterfall" methodology for software design and development. The basic process involves a straightforward, trickledown approach to design and development. The resulting documentation provides a solid foundation of information for the writer as well as a way to track the progress of the project. In this process, you have the following set of core documents:
Latest Articles