Re: Writing documentation for developers

Subject: Re: Writing documentation for developers
From: Ned Bedinger <doc -at- edwordsmith -dot- com>
To: "Brasel, Russell" <russell -dot- brasel -at- hccredit -dot- com>
Date: Fri, 10 Nov 2006 12:30:58 -0800

Brasel, Russell wrote:

What a subject for Friday, but here goes:

Apart from writing all the help documentation for our new proprietary
software, I have to go back and look at the procedures we're importing
from the old system to the new one.

And is this concerned with the customer and billing system upgrade you mentioned in a subsequent email?

That involves deciphering
PowerScript and SQL code-generally the stored SQL procedures.

I see. You don't want to trust the .NET developers to interpret it themselves. If you will excuse my officiousness, I have to ask how this code deciphering became the tech writer's responsibility?? Do other tech writers do this kind of thing? Anybody?

I can imagine a tech writer trying to get a leg up on the documentation tasks, and I would do the same in your position, but if you're on a team that is re-engineering a customer billing system, SOMEONE should be looking for the original specification that guided the existing system's design. Do you know if such a document exists? Have the people who created the orignal system left the company?

Not that yours would be the first system ever put into production without such a spec, but if your team is trying to reverse-engineer the existing system (or just the data manipulations in Powerscript/SQL) in order to document what it does, then a tech writer could reasonably expect to have a responsible manager nearby, and a database professional writing the functional specification.

I don't mean to sell you short, Russell, but what I think you're asking, in the context of customer billing system upgrades, is a bit of a stretch for me.

What we
want is a document we can hand to our contract developers so they can
see how the old code worked and write the new code in a .NET
environment. (I'm not sure what language we're using in .NET yet-it's
not that important to me.) What I have so far is a short document with
the following four headings:

Overview-what the program does.
Data Selection-how the stored data is selected.
Data Exclusion-exceptions to selection requirement.
Processing-what we do with the data (create batch files, reports, etc.)

I know enough about SQL to know what the code is doing, but that's my
current limit. For those of you out there who have worked with
developers during a transition like mine, I'd like to know if what I've
described is sufficient for a new developer who's not familiar with the
old system.

Here's a page from an old methodology (I've posted it here before, sorry if you've already seen it).

My analysts and developers were FORCED to use an entire methodology like this on a similar-sounding project.

BTW, we used contract programmers to decipher the exiting data manipulation code. They got a data dictionary, and they got access to our analysts and developers, and their work was rigorously reviewed and signed off by responsible managers, before time was spent on developing their output into a new system.
*
http://tinyurl.com/yzw2ah*


Good Luck (and have pity on yourself! Consider pushing back some of this responsibility).

Ned Bedinger
doc -at- edwordsmith -dot- com



Thanks,

RGBrasel
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

WebWorks ePublisher Pro for Word features support for every major Help format plus PDF, HTML and more. Flexible, precise, and efficient content delivery. Try it today! http://www.webworks.com/techwr-l

Easily create HTML or Microsoft Word content and convert to any popular Help file format or printed documentation. Learn more at http://www.DocToHelp.com/TechwrlList

---
You are currently subscribed to TECHWR-L as archive -at- infoinfocus -dot- com -dot-
To unsubscribe send a blank email to techwr-l-unsubscribe -at- lists -dot- techwr-l -dot- com
or visit http://lists.techwr-l.com/mailman/options/techwr-l/archive%40infoinfocus.com


To subscribe, send a blank email to techwr-l-join -at- lists -dot- techwr-l -dot- com

Send administrative questions to admin -at- techwr-l -dot- com -dot- Visit
http://www.techwr-l.com/techwhirl/ for more resources and info.


References:
Writing documentation for developers: From: Brasel, Russell

Previous by Author: Re: Traveling Tech Writers (was Too Old?)
Next by Author: Re: TechCommPros mailing list
Previous by Thread: Writing documentation for developers
Next by Thread: RE: Writing documentation for developers


What this post helpful? Share it with friends and colleagues:


Sponsored Ads