Fwd: Help in Planning

Subject: Fwd: Help in Planning
From: Jean Ostrem <jostrem -at- tdl -dot- com>
To: techwr-l -at- lists -dot- raycomm -dot- com
Date: Thu, 15 Jun 2000 08:45:05 -0700

Sona Mehta <sona -dot- mehta -at- haysmt -dot- co -dot- uk> wrote:

>How do I tell what are the last level tasks that I will be doing even
>before I understand what needs to be changed in the document? I know the
>higer level tasks like
>1. Understanding the code (Very difficult, any suggestions on how to go
about it?)

>From your post, I assume that you don't read C code. While that
would be a useful skill to learn, for now:

1.) Opening the code in a text editor and reading comments. With
luck, the coder who left will have left enough information for
you to know what to expect. If not, then urge that your company
use more comments. Warning: read a copy of the source code, or
else open in read-only mode.

2.) Sit down with a coder. You could just pick his/her brains,
but it would more useful in the long run to ask for a basic guide
to reading code. For your purposes, you may not need to read code
fluently. You might be able to get by with a few basics to point
you to the parts of the code you need to read.

3.) Get a basic programming book, and learn some of the basics
yourself.


I missed the original post, but I assume you've been tasked with writing some API documentation. Please disregard if you were asking about something else.

Bruce's suggestions are good, although I would reverse the order.

You simply can't write C API documentation without learning at least the basics of C. Writers who trust the comments often produce poor API documentation. I've seen it happen far too many times that the coder comments something one way, changes the code, and fails to change the comment.

If you don't already know at least one programming language, I'd encourage you to convince your company to pay to send you to an introductory programming class that uses the C or C++ language.

When I learned C, I bought a great book called "The C Puzzle Book" by Alan R. Feuer. It had little code snippets that you had to trace through by hand to find out what they produced. It's great practice for tech writers, who often end up reading code more than they end up writing code. Unfortunately, the book dates from the early 80s, and I doubt that it's still in print. But you might look for something similar.





Previous by Author: Fwd: Re: us vs. them (somewhat long)
Next by Author: RE: E-Commerce?
Previous by Thread: Help in Planning
Next by Thread: Fwd: Help in Planning


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

Sponsored Ads


Sponsored Ads