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.
This was a good question from a person in private mail. I am stripping out the
person's name to respect her privacy.
We were discussing how to handle the never-ending amount of changes that
developers make to a product.
> So how do you manage this client? I spend a lot of time QAing my Help where
> I "discover" a lot of UI changes that no one told me about. I am worried
> that I may not of "discovered" all of the changes. These guys never
> eventually tell me. I had a confrontation with one of the developers on
> Friday and he said that he thought I understood the application and that he
> didn't need to inform me of changes. Sheesh!
Engineers are notorious for making changes and not telling people. A few
strategies Anitian Consulting uses:
- Find the Build Engineer
Find out who does the builds and become his/her best friend. Many build
engineers have a bulk e-mail list they use to inform the development team of
when a new build is released. Get on this list. Find out where the builds are
stored. Get access to this server. If you need, get whatever version management
(VM) software the developers use and logon to their VM system.
- Become QA
Get used to being a part-time QA engineer: installing, configuring, and
checking the product is a fact of life. You need to be a super-power user of
whatever products or designs your documenting.
- Scope yourself.
Do not assume responsibilities that are not yours. Don't assume you are the
sole "advocate for the user" and take on QA roles that are not explicitly
delegated to you. Engineers are a wily bunch. You have to build a rapport with
them before you can criticize their work. Moreover, you could end up spawning
your own problems. Perfection is impossible. Settle for progress. Remember -
there is always next rev (that's a commonly uttered line at the Anitian
offices.)
- Write to reality
This is a little personal philosophy. I have a writer on site right now who is
quite skilled. But she tends to "overthink" problems and as such writes to
perception rather than reality. She documents what she THINKS things will
become and not what they actually are. One of the best and most honest ways to
display the intense dumbness of engineers is to merely document that dumbness
as matter-of-fact as possible. Dumbness only needs to be exposed to be
acknowledged. Thus, document exactly what you see. Don't try to reason out
everything.
- Write Top-Down
Our documents are very complex with a lot of technical concepts to explain. To
handle the ever-changing nature of the documents we try to document in top-down
method. We write all the high level conceptual stuff first and then fill in the
detailed task-oriented instructions later. There is actually numerous benefits
to writing in this manner. Many writers try to grab on to all the user
instructions before understanding the product as a whole. You'll do yourself
and your users a world of good to learn the product and the concepts behind it
first and then deal with the task-oriented work later.
- Be patient
Don't doc if you know things are in flux. Too many writers grab on to a
concept or an instruction set early on in the project and they refuse to trash
it later on. Honestly, we do close to 75% of our work in the closing days of a
project. We wait until things settle then blaze through it fast.
- Get a Proxy Geek
The best thing in the world to a successful doc project is a proxy geek: an
engineer or developer who serves as your gateway to all tech issues. You funnel
everything to him and he handles translating it to the other side. When I bid a
project I ALWAYS ask my client to identify my technical source. That person
becomes by best buddy in the world as I start feeding him questions and
presents.
Those are my strategies. I am sure other people might have some, hence I posted
this publically.
Ultimately, the key is to never allow yourself or your team to get cut off. You
have to take the initiative to bond with the engineers. They are not going to
come to you and say "here is the software, please criticize it for us."
Andrew Plato
__________________________________________________
Do You Yahoo!?
Yahoo! Calendar - Get organized for the holidays! http://calendar.yahoo.com/
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Develop HTML-based Help with Macromedia Dreamweaver! (STC Discount.)
**NEW DATE/LOCATION!** January 16-17, 2001, New York, NY. http://www.weisner.com/training/dreamweaver_help.htm or 800-646-9989.
Sponsored by SOLUTIONS, Conferences and Seminars for Communicators
Publications Management Clinic, TECH*COMM 2001 Conference, and more http://www.SolutionsEvents.com or 800-448-4230
---
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.
