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.
>However...here's my problem. A certain piece of code does
something. If
>you use that piece of code, you will do the same thing, or
close to it,
>depending on how you tweak it.
>I'd like to believe that the original piece of code was
written to do
>something the way the TARGETED USER needed something to be
implemented
>(as opposed to how the developer thought it should be
implemented).
This must be true since the piece was written according to
use cases, user requirements and design planning, right?
I almost prefaced that comment with a remark about it being
tongue-in-cheek. But in the final analysis, so much
programming is done in the immersive context of a larger
program, that transplanting it to another program can take
fairly surgical attention and patience, along with analysis
of the existing program and the target program. That can
become a lot of overhead instead of an efficiency.
>By reusing that code, the developer who is reusing the
piece of code is
>implementing something the way the previous user needed it
to be
>implemented and the new developer doesn't know who that
user was or what
>the user's needs were.
Are you waiting for the other shoe to drop? You would know
because the previous development was attended by Project
Documentation with Use Cases and Specifications! If you
have comments fit to be printed, I'd be interested in
discussing how the time and effort to document a project is
a good use of resources. It seems like fertile ground for
tech writers to grow value-adding documents.
As for my experience, I have a few examples of the benefits
derived from being the tech writer and included on a project
from project inception. But most project docs (even the
specifications) I've been tasked with have been
afterthoughts, if they've been written up at all.
I like to imagine that developers have their own cache of
informal project documentation that they don't ever release
to technical pubs because it serves their needs without
further ado. In this fantasy, you (as developer) would have
access to the developer documentation cache. In an
elaborate version of this fantasy, tech writers would have
access also, using these developer notes as source material
for documentation.
>How does the new developer avoid the pitfall of presenting
the
>functionality in a way that might have been appropriate for
the original
>targeted user, but differently for the new one?
This may ease or aggravate your information needs:
The problem I've seen in integrating detailed development
methodologies, such as SEI recommends, are that
methodologies add a lot of documentation overhead to the
developer workload. The other common complaint is that
"this methodology doesn't capture our project."
I've been trying to understand UML (Unified Markup Language)
as a development tool that is more manageable for
documenting software design. In a way, it could satisfy as
documentation of re-usable code, if it is done with
sufficient UML-represented detail. Then you could use XML
documents and queries to pull that information from the UML
when you're looking for suitable re-usable code.
Granted I've never done this. It seems thinkable, though,
and could be a way for tech writers to use XML to create
documentation of re-usable code. I am always up for
speculation and experimenting with new types of
documentation, but getting a shop to buy in to such a
deliberate and detailed methodlogy would be a necessary
first step, and possibly the highest hurdle.
Ned Bedinger
Edwordsmith Technical Communications Co.
doc -at- edwordsmith -dot- com http://www.edwordsmith.com
tel: 360-434-7197
fax: 360-769-7059
ROBOHELP X5 - ALL NEW VERSION. Now with Word 2003 support, Content
Management, Multi-Author support, PDF and XML support and much more!
Now is the best time to buy - special end of month promos, including:
$100 mail-in rebate; Free online orientation on content management
functionality; Huge savings on support and future product releases;
PLUS Great discounts on RoboHelp training. OFFER EXPIRES April 30th!
Call 1-800-358-9370 or visit: http://www.ehelp.com/techwr-l
---
You are currently subscribed to techwr-l as:
archiver -at- techwr-l -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.