Writing system requirements can be a daunting task. Most software products are built by teams of developers, and each component of the software may impose different requirements. The situation gets even more complicated if the system requirements must cover an entire product line. Combining all of this information into a comprehensive document is no simple matter.
So who is best equipped to handle such a task? Should technical writers write system requirements? Or should it be left to those who have more detailed knowledge of the software?
System requirements demand communication
From experience, I'd say that getting accurate requirements for each product or product component is the easy part. A good software engineer will be able to provide such details without much difficulty. They may need to chat a bit with others on their team to get the details right, but in the end they should be able to produce requirements for their code.
However, writing system requirements is really about organizing details from multiple developers or product teams into a complete final document that everyone agrees on. This can be a project management nightmare.
Often system requirements will need to be reviewed multiple times by people from many different development teams. Review comments from one team may conflict with those from another team, and getting a definitive answer can be tough.
Your Sales department may voice concerns if the recommended requirements are too high for a significant number of customers. If the software will run on computers that fall below the recommended requirements, more customers can purchase the software. Customer Support will also have essential feedback based on user calls that conflict with the stated requirements.
Legal issues should be considered. If your software requirements mention operating systems or products from other vendors, you will need to include the appropriate copyright information when you mention those products. This task requires research skills.
Communication with your publications department or web team will be necessary when it comes time to deliver the completed system requirements to your users.
System requirements are difficult because they impact almost every department in the organization.
So who would want such a task?
Writing system requirements is about gathering information, organizing it into a comprehensible document, ensuring that everyone agrees on the content, and then handling any pre-publishing tasks before handing it over to the appropriate people for delivery to your customers.
Isn't that what technical writers do every day?
Most technical writing departments will have established relationships with all of the departments necessary to produce system requirements. And an experienced technical writer will have the skills necessary to combine complex technical information into a user-friendly document, handle the politics of a messy review process, and prepare the document for delivery.
Should technical writers write system requirements? Absolutely. But they should do so using feedback from the appropriate people.
System requirements demand a team effort, but they are still documents. And documents are what we do best.
4 comments:
I tend to refuse to MS-Word clerking tasks. A System Requirements document is a no brainer and there is no reason to hand it to the tech writer. Tech writer ought to focus on what they do best: writing use-case based documentation, carrying out a task nalysis, simplifying complex data.
I can understand that approach. You have to be especially careful if you work in an environment where your skills are underappreciated.
However, I recently worked on system requirements that spanned a whole suite of products. The requirements differed quite a bit because some were CD applications and others were web-based. That document required a lot of project management, communication, and technical analysis.
Could someone else have completed the system requirements? Sure. But it would have taken them much longer.
A technical writer combines all of the necessary skills in a single person. Why assign the requirements to someone who is less equipped to do the job?
But I agree that you have to balance such jobs with more writing-intensive tasks to avoid the "formatting monkey" label writers often earn in an environment where their skills are under appreciated.
Thanks for the though-provoking comment, Avi!
I've had experience as both a technical marketing specialist, a SW systems analyst, and a technical writer, and out of all of these roles I can very truthfully say that I prefer to be the writer on a SW project rather than the person responsible for authoring the system requirements and specifications.
As a SW analyst, most of my time was spent in authoring and maintaining monotonously-worded high-level user stories in atrociously-formatted PSDs, churning out countless revisions of UML workflows at various levels of granularity, and keeping everyone in the project on task and conflict-free (i.e., project management, a job in itself!).
As a writer, I am actively involved in contributing to and verifying the task-based use cases/stories so painstakingly authored and maintained by the analyst (poor them!), while still having the opportunity to work directly with the marketing and SW development teams to address any lingering UI design or usability issues vetted by the authoring process.
I would have to say that in my experience on both sides of the requirements fence, that I think it would be difficult for one person to act as both analyst and writer for a SW project following Agile development best practices, as their time would need to be split between constant revision of both system requirements (for engineering and testing) and documentation (for end-users).
I have also found that as long as the project team is open to involving the writer earlier in the design and development stages of a SW project, then the writer can have an impact on the development of SW requirements, the granularity of user tasks/workflows, and UI instructional content and design, all of which will make the job of documenting the SW all the easier.
Carol, thanks for the insightful post. It's great to hear from someone who has seen these issue from multiple roles.
I think your point about being involved early in the design and development process is especially important. Technical writers have so much to contribute at that stage, and writing the documentation is so much easier when the product is designed with users in mind from the beginning.
Thanks for commenting!
Post a Comment