Style guides, conventions, standards and plans (was: anyone else in the same boat?)
Conventions and standards only have meaning to a team of tech writers. ... A lone writer should do this in his/her head.
Some lone writers may be able to keep all their (style, conventions, standards) decisions in their heads. I've never been able to, so I write them down for my own use, even if I'm the only writer on the project. (Yes, I've worked as a technical *writer* as well as a technical *editor*.) Perhaps that's because I tend to work on more than one project at a time (which don't all use the same styles and conventions), but I doubt I'm the only person who needs a memory-jogger.
I don't think lone writers need to (or should) spend a lot of time developing a full-blown style guide, but they (and the documents they produce) will probably benefit from keeping a record of the decisions they make about style and presentation, so they don't have to keep all those decisions in their heads while they're also trying to understand the product they're writing about. It also depends on what you mean by a "style guide." Many people include material that I'd consider part of a "design guide" or a "process guide." See my article at http://www.wrevenge.com.au/eyrie/tenews4.htm#feature4 for more on that subject.
Planning, now, is a different matter. Again, spending days (or weeks) on a detailed documentation plan may be quite unnecessary for a lone writer, but planning ahead does generally save any writer a lot of time further down the track. Especially for an inexperienced writer, "making it up as you go along" can mean a lot of avoidable rework. An experienced writer may be able to get away with a "sketch plan," but an inexperienced writer may not.
As others on this list have pointed out, writing a documentation plan has other advantages. The writer can use it as a discussion or negotiation document with the client or the software developers or whoever has to approve what the writer has produced. If the writer is producing online help, it's *very* important to get agreement on how the help is being attached to the product (including what you and they mean by "context-sensitive," if that term is being used); otherwise the help may not work the way the writer designed it.
Having said all that, I do agree with this statement from Andrew and some of his related comments:
"If you don't have the skill to implement things and get the job done - it doesn't matter how much you plan."
That's certainly true. Planning is necessary, but it's definitely not sufficient.
Regards, Jean
Jean Hollis Weber
mailto:jean -at- wrevenge -dot- com -dot- au
The Technical Editors' Eyrie http://www.wrevenge.com.au/
Avalook at Australia Travel site: http://www.avalook.com.au/
-----------------
Now available: Editing Online Help, a tool-independent introduction to planning, developing, and editing online help systems. For a table of contents, go to: http://www.wrevenge.com.au/bookshop/olhbk.htm
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Develop HTML-based Help with Macromedia Dreamweaver! (STC Discount.)
**NEW DATE/LOCATION!** January 16-17, 2001, New York, NY.
http://www.weisner.com/training/dreamweaver_help.htm or 800-646-9989.
Take XML and Tech Writing courses online! Our instructor-led courses
(4-6 hrs/wk) give you "hands on" experience at your convenience. STC members
get 20% off! http://www.online-learning.com/index.html.
---
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.
Previous by Author:
Re: Writers vs Editors
Next by Author:
Re: Writers vs Editors
Previous by Thread:
RE: oddball Word questions (involving making multiple documents into one book)
Next by Thread:
Standards/processes versus content
Search our Technical Writing Archives & Magazine
Visit TechWhirl's Other Sites
Sponsored Ads