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.
Subject:Re: This list mirrors real life From:"Bob Hooker" <rlhooker -at- flashcom -dot- net> To:"TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com> Date:Sun, 23 Jul 2000 22:20:26 -0400
As the one whose original post asking for information on requirements,
specification, etc., documents may or may not have been involved in
triggering this thread (I'll admit to being about as paranoid and
thin-skinned as they come, and there were a couple of requests along the
same lines at about the same time) I was rather surprised by the reaction it
seems to have generated.
As a matter of fact, I did spend a fair amount of time with search engines
on the Web trying to find what I was looking for. What I turned up was a
number of sites that offered courses in writing reqs and specs, or software
to help write them, and other sites assuming basic knowledge about them. No
site, that I could find, had what I really needed, which was What does one
of these things look like? What makes a good requirements or specifications
document? What are the resources? Who are the experts in the field? How do I
know the Web site of an expert if I stumble onto it?
Try this analogy: As a tech writer, you've been asked to write a help file
about something. Problem is, you've never seen a help file before in your
life. (This is admittedly rather far-fetched, but it's the best I can think
of right now.) You go to the Web to see one and end up at places like Blue
Sky and ForeFront, offering you software to build help files, or at training
company sites offering courses on how to use software to build help files,
but there are no examples of help files or anything about what makes a good
help file, or even what a help file is. So, I would think, you'd turn to
TECHWR-L, knowing that it's probably full of people who know about help
files, and ask just what one of these critters is, and, hopefully, get a
pointer to some useful information and maybe even an example or two. (After
all, we as tech writers know that if a picture is worth a thousand words, a
good example is worth two-thousand, don't we?)
So, I posted the question about reqs and specs to the list and got some very
good responses from some very kind and knowledgeable souls that pointed me
to just the kind of information I was looking for. Now maybe you, gentle
interlocutors, could have found the same info, and recognized it's
relevance, in 10 minutes of Web surfing, but I couldn't. To you, I extend my
congratulations, three hip-hip-hoorays, and two attaboys.
> Someone sends out a message that they are looking for samples of
> Requirements Documents (or API document, etc.). It takes 10 minutes
> for the post to make the list, and a day or two before enought people
> respond with lists of resources to make the answers worth while.
> Instead, in 10 minutes, if the person had spent that time with their
> favorite search engine (google and dirtpile are two excellent ones
> that I use), they'd have the answer and be on their way.