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.
-------------------------------
csouther writes:
My companys software is increasingly becoming more Web-based, which
means there are lots of different 3rd party applications (mostly
Microsoft) that it requires and whose options you need to tweak.
My VPs take on this is that if it affects the use of our applications,
then we need to document how to configure these 3rd party applications.
-------------------------------
I cringe at this thought, but if it needs to be done, then it needs to be done. If this is a Web-based application, I'm assuming part of what you're documenting is perhaps server installation--at which point you would be producing a document that steps you through how to do this?
If that's the case, just give users the info they need to get the job done. Don't get bogged down in explaining how to get to the different dialogs/popups/screens that people will use. Each version of Windows has slightly different ways of accessing the same dialogs, and if you're not careful, you could end up with a nasty laundry list of optional steps just trying to tell the user how to get to something like Services. You will probably also end up having to maintain different docs for each version of Windows server, and perhaps even each service pack (not sure on this though). So yeah, if you can avoid all of this, do it. If you can't, roll up your sleeves and enjoy the ride. :-)
As for linking to, or including, 3rd party documentation, that could become a bigger hassle then writing multiple manuals. You would have to have one set for each version of the 3rd party software, and your delivery guys would have to know which documentation version to burn. If you're just dealing with Windows, this might mean WinNT, Win2000 server, and Win2003 server. If you're dealing an application, Word for example, you could have several more versions to choose from. If your Web application is using more than one of these third party apps, suddenly you have an exponential number of combinations to burn. This, of course, can be handled, but I'm willing to bet that it's not something that your delivery guys/gals (or whoever it is who is responsible for burning these CDs) will want to do. Now, without knowing anything about your situation, you could also run into the problem of some of your users using multiple versions of these 3rd party apps. How do you ensure that the user using Awesome Application v2.0 will get the v2.0 docs and the user using Awesome Application v3.1 will get the 3.1 docs? So burning, and even linking, should just be left out.
Now, in the past, what I've done is put one simple line:
For more information, consult the YYYY documentation.
Done and done.
This has been my experience at least.
********************************************
Sean Hower - communications specialist http://www.seanhower.com
_____________________________________________________________
Create your own web site for FREE at http://www.freehomepage.com
WebWorks ePublisher Pro for Word features support for every major Help
format plus PDF, HTML and more. Flexible, precise, and efficient content
delivery. Try it today!. http://www.webworks.com/techwr-l
