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.
RE: Teaching a practical business writing class and looking for professional rubrics
Subject:RE: Teaching a practical business writing class and looking for professional rubrics From:Paul Hanson <phanson -at- Quintrex -dot- com> To:techwr-l List <techwr-l -at- lists -dot- techwr-l -dot- com> Date:Mon, 17 Aug 2009 15:04:44 -0500
These comments are meant to highlight not considering that maintaining the document being written is part of the job. I'm using a 750 page Word doc that is a user guide for software that I reviewed last week. There will be enhancements made to the software so the document will need to be revised.
There were three things that I picked up on immediately.
1) There were no styles - everything was manually formatted Normal,
2) The 5 page TOC was manually typed. Not all entries were hyperlinks,
3) No Index.
If the writer had thought about "after the doc is done and I'm writing a new section for the doc" - instead of focusing on the immediate writing task - it is my opinion the writer would have thought about the following which, presently, there is no evidence the writer considered these ideas:
1) Related to styles, what if my manager wants me to change all my section titles to Times New Roman instead of Arial? What if I have to change all my references to the buttons in the software from bold to bold/italic? Will I have to manually go through this 750 page monster, page by page, paragraph by paragraph, finding each and changing it?
2) related to a manually typed TOC, what happens if I add a new section between pages 350 and 351. Will I really have to figure out how the change trickles through the rest of the pages in the doc? That's 1/2 of the doc that has to be evaluated.
3) related to the lack of an index, is this document usable if there is not an index? If I want to find out information about the "Whatever" module, can I find it through the TOC or would it be easier to use an Index?
In summary, teach them to consider how the user will actually "use" the document that is being written and how they will incorporate changes to the document as revisions are made to the software or subject area, if not they are not writing documentation for software.
PS: The lack of an Index kills me. How many of you have written a 750 page user guide or technical manual that did not have an Index? Am I being snobbish?
Paul Hanson
Technical Writer
Quintrex Data Systems http://www.quintrex.com
email: phanson at quintrex.com
-----Original Message-----
From: Rob Hudson
<snip>
To ask it another way, what are the most common mistakes or problems
you see from new writers in the workplace? I can back those ideas into
criteria for assignments.
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Free Software Documentation Project Web Cast: Covers developing Table of
Contents, Context IDs, and Index, as well as Doc-To-Help
2009 tips, tricks, and best practices. http://www.doctohelp.com/SuperPages/Webcasts/
Help & Manual 5: The complete help authoring tool for individual
authors and teams. Professional power, intuitive interface. Write
once, publish to 8 formats. Multi-user authoring and version control! http://www.helpandmanual.com/
---
You are currently subscribed to TECHWR-L as archive -at- web -dot- techwr-l -dot- com -dot-
