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.
Jim Barrow lamented:
> Sent: Saturday, March 22, 2008 14:39
> To: techwr-l -at- lists -dot- techwr-l -dot- com
> Subject: UML 2.0
>
> Last Thursday our Tech Pubs group received a request to start using
UML
> 2.0.
> The reason for this is that the head of the engineering department
wants
> to
> generate code from these UML diagrams. This is the premise. Here's
the
> background.
The implication seems to be that you guys-and-gals in TechPubs could
replace a lot of code developers, is that correct?
I knew next-to-nothing about UML before seeing your post, so I Googled
and Wikipedia'd a bit. It seems that some of the UML tools listed at http://en.wikipedia.org/wiki/List_of_UML_tools
claim that they can reverse-engineer C++, Java, etc. code.
So, in your position, my first move would be to verify that Visio (and
whatever other tool your head of Engineering imagines to be both
necessary and sufficient for his grand scheme) is unable to perform such
reverse engineering.
Then, I'd obtain one of the tools that _does_ support reverse
engineering of whatever OO language(s) your company uses, and let it do
its thing on code that your company has already produced and released.
Run a private trial first, so that you'll know what to expect, then do a
more public trial.
First, see what kind of UML your company's existing code yields.
Then, see how well that generated UML compiles (using the same tools)
back into C++ or whatever. IF/WHEN that fails, snag a developer to tweak
the existing company code until it _does_ pass smoothly through the
reverse-eng and forward-compile process. Document how much of such
effort was needed.
If these tools are going to work well enough for prime time in the
forward direction, they should darn well work as well as they claim in
the reverse direction, for code that you already know is "good enough"
to ship.
After that, take some usefully-large-but-manageably-small hunk a burnin'
code - again, already existing and working well enough that your QA
dept. let it ship - and attempt to write the UML that completely
describes that code (sufficient to regenerate that exact code or its
functional equivalent that would plug right into your company's product,
compile perfectly with the overall project, and work as well as the
existing code that you started from. In other words, this part is a
trial run to see what your group would need to do to UML your way to a
selected module of the next releasable code project (while the rest of
Engineering is going to continue doing it the old fashioned way until
the UML approach proves itself).
You might even want to get SQA in the loop to spare a few cycles to test
the generated code as part of a variant of the previous release. First,
they've got a legitimate interest in this project, and second the more
people and groups you involve (even just peripherally), the more this
evaluation takes on momentum as a real project.
Take the time that you reasonably need. Take the resources (programmers,
etc.) that you reasonably need. Document at every turn. Document how you
did or did not accomplish the goal. Document every obstacle and what it
took (time and personnel resources.... time-is-money) to resolve.
Indicate stuff that you've learned once and wouldn't have to repeat.
Indicate stuff that has been discovered that would need to be repeated
during every future project cycle, especially if it's a failing of the
tools or of the overall UML state-of-the-2.1-art.
Try not to cheat. That is, it might turn out that the UML-to-code path
IS the way to go, for your company, or that it's worthwhile adopting for
some defined subset of what your company does, so don't shoot the effort
in the foot with pre-conceptions. . . don't pad your time estimates or
drag your feet while doing the trial . . .
If you pooh-pooh from the start, the head of Engineering might decide
that you'd let your negative expectations overshadow the evidence and
find somebody who will give him the answer he wants, to your eventual
detriment. Instead, just bustle about, efficiently going about the
evaluation process that he has mandated, generating lots of
memos/e-mails among the "working group" (you get to decide who they
should be, and if anyone balks, direct her/him to the head of
Engineering), checking in when you encounter resource or other
roadblocks, publishing meeting/progress minutes, tracking expenses.
Look shocked and aghast if anyone even obliquely suggests that this
effort is anything less than a full-blown company project, just like the
projects to get the next release of product out the door. Because, if
the head of Engineering is serious about this infatuation, then this
_is_ a serious company project, that will need resources and tracking...
and you're just the man to do it. :-)
Cheers,
Kevin
The information contained in this electronic mail transmission
may be privileged and confidential, and therefore, protected
from disclosure. If you have received this communication in
error, please notify us immediately by replying to this
message and deleting it from your computer without copying
or disclosing it.
Create HTML or Microsoft Word content and convert to Help file formats or
printed documentation. Features include support for Windows Vista & 2007
Microsoft Office, team authoring, plus more. http://www.DocToHelp.com/TechwrlList
True single source, conditional content, PDF export, modular help.
Help & Manual is the most powerful authoring tool for technical
documentation. Boost your productivity! http://www.helpandmanual.com
---
You are currently subscribed to TECHWR-L as archive -at- web -dot- techwr-l -dot- com -dot-
