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.
And yes, the upfront design of a documentation set is usually not ever
performed, legacy documents are maintained and added to, with new ones
falling into place as you go along. Of course then, when you rename things
to make them sensible and consistent, outcry!
Can't win. ;-)
Gordon
_____
From: Fred Ridder [mailto:docudoc -at- hotmail -dot- com]
Sent: 13 February 2008 13:51
To: Gordon McLean; techwr-l -at- lists -dot- techwr-l -dot- com
Subject: RE: "Developers Guide", "Developers' Guide", or "Developer's Guide"
Gordon McLean wrote:
> Which prompts me to ponder why the other types aren't titled:
>
> Using [product name]
> Developing with/on/for ...
>
> In other words, if an Installation Guide is focussed on the task of
> installing a product, why aren't the others focussed on the tasks of
using,
> developing, maintaining, administering... etc.
If parallelism is the goal, these titles still have a problem unless you
give
the guide that covers installation a title of the form "Installing [product
name]". And while I do like using verb participles (sometimes referred to
as gerunds, even though they are usually not being used as nouns) in
headings that idenitfy procedures, I'm not crazy about them in titles
of works.
But what *can* work in many cases is to form titles with the noun
for the task being documented rather than the person performing the
task, as in:
Administration Guide
Development Guide (or perhaps Application Development Guide)
Installation Guide
Maintenance Guide
The one place where this approach is awkward is the classic one,
namely the user's guide. But part of the problem may be that this
title is often used for a catch-all document that contains information
on multiple tasks (e.g. installation and configuration as well as how
to use the product, plus some reference information just for good
measure). So the problem may be a more fundamental one of
information design than a simple matter of an awkward title.
____________________________________________________________________________________________________
This email (and any attachments) is private and confidential, and is intended solely for the
addressee. If you have received this communication in error please remove it and inform us via
telephone or email. Although we take all possible steps to ensure mail and attachments
are free from malicious content, malware and viruses, we cannot accept any responsibility
whatsoever for any changes to content outwith our administrative bounds. The views represented
within this mail are solely the view of the author and do not reflect the views of the organisation
as a whole.
____________________________________________________________________________________________________
Graham Technology plc
Registered in Scotland company no. SC143434
Registered Office India of Inchinnan, Renfrewshire, Scotland PA4 9LH
Create HTML or Microsoft Word content and convert to Help file formats or
printed documentation. Features include support for Windows Vista & 2007
Microsoft Office, team authoring, plus more. http://www.DocToHelp.com/TechwrlList
True single source, conditional content, PDF export, modular help.
Help & Manual is the most powerful authoring tool for technical
documentation. Boost your productivity! http://www.helpandmanual.com
---
You are currently subscribed to TECHWR-L as archive -at- web -dot- techwr-l -dot- com -dot-
