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.
> software-development life cycle has no definite phase for documentation.
> * Is such a situation normal in a software company?
Yes indeed.
>How does one produce good documentation in on schedule in a setup such as this?
Planning. Discipline. Hard work. Resourcefulness. Prioritization.
If your product is any good and has much complexity then there should not be much change in the weeks before commercialization. To ensure good quality, there usually needs to be extensive testing of a stable baseline (software version) BEFORE it goes out to the client. (Of course, some companies skimp on the beta testing, ship a product that hasn't been tested properly, let the clients find bugs, then issue patches.)
The bulk of my doc work gets done in the late development stage and during beta testing. This requires discipline and planning.
E.g. I ensure I'm up-to-date in my other responsibilities, so I can focus on the urgent task. Also I try to work out, well before this critical stage, all the details like help formatting, production workflow, etc.
General efficiency/productivity tips in no particular order:
- Get granularity right: do not give any more detail than necessary. E.g. say some programmer arbitrarily sets the connection timeout to 60 minutes. Don't document this detail and thus expose the doc to a risk that the parameter will be arbitrarily changed to 50 minutes, making the doc wrong. Just state that the session will time out after a lengthly period of inactivity (if this is good enough).
- Get the facts: don't waste your time reading spec sheets. Even with the best intentions they usually contain much that is apocryphal. Use the product. Talk to the developers, marketing people, testers, talk to users, identify their needs so you can focus on the stuff that matters.
- Screenshots: are they absolutely necessary? No? Delete them. Put them back in at the very end IF YOU HAVE TIME. Note that "you have time" means now and in the future. Screenshots can be a localization and maintenance nightmare.
- Don't get bogged down with your tools. Don't fall into the trap of implementing features in the help system, just because RoboHelp provides a widget for doing it "easily and automatically". All help is accessed via contexts-sensitivity or the search or the index? Dump the TofC. Compile it at the end -- if you have time.
- Reuse content whenever you can. Hunt up marketing materials and white papers, which can be very good at giving conceptual descriptions of the functionality.
- Be minimilast in content, or at least prioritize. First, document the things that the users really couldn't do without, and IF YOU HAVE TIME, document the stuff that the users could figure out with minimal effort. By minimal I mean not much longer than it takes to look it up in the help.
NEED TO PUBLISH YOUR FRAMEMAKER CONTENT ONLINE?
?Mustang? (code name) is a NEW online publishing tool for FrameMaker that
lets you easily single-source content to Web, intranets, and online Help.
The interface is designed for FrameMaker users, so there is little or no
learning curve and no macro language required! See a live demo that
will take your breath away: http://www.ehelp.com/techwr-l3
---
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.
