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.
> Does anyone out there have any strong opinions about document numbering? I am
Yes. Keep in mind that the PRIMARY goal of any technical document is to
communicate information in an effective way. You have to consider the
nature of the material and the nature of the persons who will be reading
and using the document (yes, there is a difference...think about it from
the user's POV). How you design the document's layout to achieve this
goal is just as important as its content, and its what we get paid the big
bucks to do.
Numbering a document serves to organize the material in easily
comprehended "chunks." Labels or titles attached to the numbers serve as
signposts to the nature of the information contained under that
particular number. Which means, for the writer, that the information
must be organized and presented in a logical manner.
> refering specifically to section numbering in design specification documents
> put together by engineers. I have seventeen subsystems that I have set up as
> 1.0, 2.0, 3.0, etc. Does it work best to use indents for subsections as you
go
> into deeper levels? My lead engineer wants everything flush left and my
> preferred method is indenting subsections. Is there a standard I should
follow
> or is it abitrary? Or should we lock ourselves in a dark room with knives
and
> see who comes out alive?!*
Ask your lead engineer how hard he wants the user's job to be when he/she
goes looking for information? The appearance of the basic page design
must take into consideration how people read. The creative use of white
space and graphics can make the job all that much easier when the user
picks up the document - not to worship at the brilliant prose or
magnificent engineering - but to find the solution to his/her current
problem.
Then go ask your sales manager how much repeat business he wants. My
experience is that the documentation represents an "aftertaste" that the
user experiences long after the first sale is done and gone -- it can be
a good aftertaste or a bad one. Good documentation reflects well on any
product. Bad documentation makes even the best product look less
appealing, especially when its time to make the next purchase.
> If the responses warrant it, I will summarize and post to the list in a week
or
> two.
> Thanks!
> Rikki
Dan Azlin ** WORD ENGINEERS, Technical Writing & Publishing **
Ph/Fax: 508-921-8908 18 School Street
Internet: dazlin -at- shore -dot- net Beverly, MA 01915-4851
