Re: Checking code (was: Software engineer tech. writers? )

Subject: Re: Checking code (was: Software engineer tech. writers? )
From: Ned Bedinger <doc -at- edwordsmith -dot- com>
To: Sandy Harris <sandyinchina -at- gmail -dot- com>
Date: Tue, 04 Sep 2007 16:15:24 -0700

Sandy Harris wrote:
> On 9/2/07, Dossy Shiobara <dossy -at- panoptic -dot- com> wrote:
>
>> Are there software-oriented tech. writers who are also software
>> engineers who can read through C source and write documentation
>> based on what it does?
>
> How many writers analyse the code they document?
>
> At one point I had access to 600,000 or so lines of a client's C code,
> so I wrote a few little grep scripts to test it a bit. Results were appalling.
> It was production code, but only used as internal test tools; it wasn't
> what they shipped to customers.

I think that really good coders are a small minority, and are hard to
finds and hire. OTOH, I've seen a lot of newbies working in dev--they're
cheeper to hire, and more likely to stay with the job because they can
grow into it. But otherwise, apart from the possibility that they used
insufficently-trained programmers to crank out 600,000 libnes of C, I
wonder if a coder who creates appallingly-coded internal tools is even
capable of doing fine work on a product they're going to ship. Good
coders wouldn't write appalling code, even for an internal tool, would they?

>
> Results I recall:

I think your efforts at grokking 0.6M lines of code are fantastic! When
a tech writer taps into the 'local knowledge' of the product and
developers, then writing projects really can run on rails. I think we
tech writers ought to have some skills and tools for getting to know the
product at many levels. The lower a tech writer can peer into the
product, the better positioned he or she is for communicating with the
team and customers.

But it boggles the mind to think of all the work and time involved in
getting to know a product this way. The job calls for a staff writer
who run alongside the development process while it is going forward, for
however many years it takes to bring a big code base to fruition. I
wouldn't want to try it as a contractor who has limited time to get it done.

>
> Under 15% of "switch" statements had a "default" case.

Sheesh, I bet they got a lot of bug reports on that.

>
> The "assert" macro was used about 5 times in several thousand lines
> by one programmer, not at all by any of the others.

Maybe they got rid of them after testing? I'm not a C programmer, its
just a guess.

>
> The C idiom for checking return value of functions that allocate resources,
> fopen(), malloc(), fork(), etc. is something like
>
> if( (fp = fopen(...)) == NULL)
>
> This was rarely used. In most cases, there was no test in following
> lines either.
>
> If you do check code this way, what should you do with your results?

With the caveat that your coders might have used custom functions
instead of the standard ones you grepped for, I do think you gathered
some interesting insights into the product, and if it were me, I would
probably inquire further with the dev lead.

> I considered passing them on to the programming manager, but did
> not do it. I figured as a contractor and "only" a tech writer, it was not
> a good idea to stir things up that way.
>

I don't think there's any harm in looking at the time you spent studying
and sizing up the code as simply ramping up on the project, and as such
your perceptions about the project are yours to build on. If you do feed
what you found back to the programming manager, I think I'd do it
off-handedly, unless I needed an answer in order to get my work done.

Ned Bedinger
doc -at- edowrdsmith -dot- com
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

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-

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%40web.techwr-l.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/ for more resources and info.


References:
Checking code (was: Software engineer tech. writers? ): From: Sandy Harris

Previous by Author: Re: Finding that first tech writing job?
Next by Author: Re: Technical author leading resistance to background checks at NASA
Previous by Thread: RE: Checking code (was: Software engineer tech. writers? )
Next by Thread: Re: Software engineer tech. writers? Do they exist?


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


Sponsored Ads