TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
I am late getting on to this thread, but this topic is a current headache
that has stopped me from reading the list.
My chief client is developing an entire cable TV network (in the
communications sense) from scratch. All new hardware, many new
communication formats, and most importantly, a new paradigm for watching TV.
Currently I have assigned three writers to writing specifications for the
project. These writers have mainly done high level architecture specs,
glossaries, business requirements, and software product requirement specs up
to this point.
The project is not moving from architecture to design and implementation. I
see the need for 8 more writers all writing specs. None of this network
software (at this point) will ever be packaged to be sold to rival cable TV
companies (the only audience for this software). I am looking at somewhere
in the neighborhood of a 1000 documents ranging from 5 page RPI's to 1000
page API reference manuals.
The argument against putting on 5 more writers is that "maybe we don't need
polished documents." The idea is that the engineers will write all the
documentation. The engineers are on my side. They are eager to work with
the writers. Personally, I think eleven writers overall are needed, but I
am cutting corners and working writers hard to get it down to 8. Only three
writers is my headache.
I know I will get the writers in the end, but it is sad that I can't put
them on when we need them most.
Now that I am done complaining, I want to address Richard's question.
Specs always exist in some form: comments in code, email, formal
specifications, UML diagrams, Test cases, etc. A spec helps write a user
manual to the extent that the implementation team follows the spec. Quite
often a spec is written and then the implementation uses it as a contractor
uses a blueprint. It defines the general project, but details may change.
The spec is often not updates to reflect the implementation changes.
Consequently, a user manual must start with a spec, but follow the code
(UI, behavior, etc.) instead of the spec. Likewise, testing starts with the
spec and follows the code. Often the user manual and reference manuals are
the replacement for the specs for testers. The manuals should be tested
against the code anyway.
that's enough for now. in short, specs should always be written and writers
should always be involved.
Writers are left out many times.
Walden
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Are you using Doc-to-Help or ForeHelp? Switch to RoboHelp for Word for $249
or to RoboHelp Office for only $499. Get the PC Magazine five-star rated
Help authoring tool for less! Go to http://www.ehelp.com/techwr
Free copy of ARTS PDF Tools when you register for the PDF
Conference by April 30. Leading-Edge Practices for Enterprise
& Government, June 3-5, Bethesda,MD. www.PDFConference.com
---
You are currently subscribed to techwr-l as: archive -at- raycomm -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- raycomm -dot- com
Send administrative questions to ejray -at- raycomm -dot- com -dot- Visit http://www.raycomm.com/techwhirl/ for more resources and info.
