Comments on HelpScribe Technical Writing: Should technical writers write system requirements...

Carol, thanks for the insightful post. It's great ...

2008-03-26T06:07:00.000-04:00

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!

I've had experience as both a technical marketing ...

2008-03-25T19:20:00.000-04:00

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.

I can understand that approach. You have to be esp...

2008-03-19T06:11:00.000-04:00

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 tend to refuse to MS-Word clerking tasks. A Syst...

2008-03-18T12:58:00.000-04:00

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.