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.
Petko M wondered: <<What would be your approach to estimating the
documentation needs for somebody who has developed a product but has
no user documentation for it and has no clear idea what this
documentation should be?>>
Spend some time learning about what the product does and who it does
it for: that is, understand the basics of the audience and how they
will use the software to accomplish their tasks. This takes less time
than you'd think if you can put yourself into the position of becoming
one of them and using the software.
<<As a freelancer, I currently have a prospect who fits the above
description. They have developed a product financed by grants from non-
profit organizations for the needs of some scientific circles. The
product is a database engine capable of fast searches that render
highly-relevant results based on indexing and some elements of
artificial intelligence. They have no specific user documentation for
it but the system integrators for their clients so far have somehow
managed to cope using the development documentation. (These system
integrators are the actual users of the product.)>>
Since the users are also the developers, a good starting point would
be to spend a day with them getting a feel for why they use the
product and what they hope to accomplish by using it. (Working with
actual "users in the wild" who have not used the product before is
also useful, but not always possible. If you can, find a way to hook
up with the beta testers and work with them too.) During this day, ask
them how they proceed with their searches and why they feel that
approach is successful, but also ask them what approaches they avoid
and why they feel those approaches would be counterproductive. You'll
find considerable agreement on some points, and disagreement on
others. Keep asking these questions as you go: any time you don't
understand why a feature exists and how it fits into the overall user
goals, ask!
Assembling the sum of these perspectives into a consensus reality will
reveal how you should approach the project. Design your documentation
to guide users through the process of defining each goal (e.g., what
they hope to find by searching), then use what you have learned about
the perceived "best practices" to define the primary approaches that
are likely to succeed, and document those practices, focusing first on
the overall steps. To support that primary approach, define when the
secondary approach (based on the advice of those who had a different
way of doing things) might be better. If you can find situations when
that second approach makes more sense, document those steps too,
accompanied by a clear description of when the second approach may be
better. The final step is to actual make the steps concrete by adding
in details of how the software supports each step.
<<I told them that I would need at least a month to get into the
specifics of their field and to familiarize myself with the product
before I could make a meaningful documentation proposal.>>
Although immersing yourself in this part of the project for a full
month would be interesting and productive, it's unnecessary. A day
will give you all you need to get started. A week would be a luxury
and would provide a deeper understanding, but wouldn't improve the
results so much that it would be worth the investment. A month is
simply not realistic. Most of what you need to learn will be learned
as you work with the developers and the software.
<<I proposed to update their existing developer documentation while
reading it (some of this documentation, they told me, was slightly out
of date) and also to rewrite some documents from the user perspective
where this perspective is immediately clear to me.>>
Updating the existing docs is very useful because most developers hate
doing this task, and they'll be pleased to offload it to you. The
resulting documents will probably be exclusively for internal use, but
will be very useful in that context. They probably won't be useful for
customers because the context is so different. But the internal
documents will be your source materials (your reference manual) when
you're writing the user documentation.
To the extent that the contents of the two document sets overlap,
you'll need to consider the possibility of some form of single-
sourcing: the more they overlap, the less sense it makes to write the
same material twice. For example, you could create two doc sets: a
goal- and task-oriented user manual that focuses on what to do and why
and how, and the accompanying reference manual that provides the
technical details for those who need to know them.
<<What would be your approach to estimating the documentation needs
for such a prospect?>>
<<How do you handle the initial “non-productive” period when staring a
new gig so that your client/boss does not get nervous waiting for your
output?>>
Easy: I entirely eliminate the nonproductive period. <g> From day 1, I
am already starting to produce documentation by defining the user
needs and structuring it into a goal-oriented outline of the doc set.
That plan won't survive contact with the enemy (i.e., the software),
but it's a highly productive starting point. That turns the early days
into a "less-productive" period, but never an unproductive period.
Essential survival skills at this point: Get to know each developer
well enough that you can find ways to avoid annoying them and instead
find a way to interact with them that they will embrace; ask them when
and how (in person, e-mail, phone) they are willing to interact with
you rather than imposing your preferences on them. (Show some respect
for their needs, and those times when you need to follow your own
preferred approach, they'll be more likely to accept that.) For
instance, some want you around only at the start of the day; others
want you only at the end or only at meetings, and others still are
happy to see you whenever the heck you feel like stopping by.
Use your connections to learn what aspects of the product are largely
stable, versus the ones that are still floating and being revised
frequently. Concentrate your efforts on the stable aspects, since that
will minimize the amount of rework required at the end of the project.
By the time you finish documenting the finalized aspects, many of the
floaters will have become stable enough to be worth your time
documenting.
--------------------------------------------------------
Geoff Hart (www.geoff-hart.com)
ghart -at- videotron -dot- ca / geoffhart -at- mac -dot- com
--------------------------------------------------------
***Now available*** _Effective onscreen editing_
(http://www.geoff-hart.com/books/eoe/onscreen-book.htm)
ComponentOne Doc-To-Help 2009 is your all-in-one authoring and publishing
solution. Author in Doc-To-Help's XML-based editor, Microsoft Word or
HTML and publish to the Web, Help systems or printed manuals. http://www.doctohelp.com
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-
