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.
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-
