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 know our support team welcomes documentation as it means that the number
of support calls and emails is reduced if the documentation is good. This
means that support, to some degree, is reliant on documentation.
Some of the other issues raised to do with readability, content, format etc
are all to do with the documentation process that is in place.
This is how we create documents:
1. Outline - an outline is written which says exactly what will appear in a
document. It is either written by a member of the docs team or an SME.
2. Outline Review - the outline is reviewed by an SME
3. Write - the document is written
4. Technical Review - the document is reviewed for technical accuracy and
completeness. This is always done by an SME. This SME may or may not be the
same as the SME who did the Outline Review.
5. Revisions - revisions made based on technical review. These revisions are
made by the writer.
6. Readability Review - this is done by a member of the docs team. I believe
that this is an essential part in the clarity, readability, grammar etc of
the document.
7. Revisions - revisions based on readability review. This revisions are
made by the writer.
8. Formatting, indexing.
Stage 8 encompasses everything that is left, basically because it's being
done by the same person.
Stage 6 onwards are "nice to have" but not essential stages.
I do think the readability review is extremely important but it's down to
pressures and timescales as to how much gets done. If we are under pressure
we try and ensure that as much as possible of the 8 stages is done although
all revisions may be done at the same time. As all documentation created by
the docs team is done in a standard template the overall formatting of the
document becomes less important because some of it should already have been
done.
The above documentation process works extremely well for us although we're
still human and the odd thing here and there does slip through the net.
*** Deva(tm) Tools for Dreamweaver and Deva(tm) Search ***
Build Contents, Indexes, and Search for Web Sites and Help Systems
Available now at http://www.devahelp.com or info -at- devahelp -dot- com
Learn about tools and technologies for user assistance developers at
The Help Technology Conference, August 21-24 in Boston, MA
Details and online registration at http://www.SolutionsEvents.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.
