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.
Subject:Re: Code documentation requirements? From:Kris Olberg <kjolberg -at- IX -dot- NETCOM -dot- COM> Date:Wed, 21 Jan 1998 21:36:29 -0600
---------
> From: Lani Hardage <lhardage -at- RMTECH -dot- COM>
> Date: Wednesday, January 21, 1998 3:37 PM
>
> What would you look for, since our company has a product written in C,
> some new code in C++ (with some APIs in the pipeline), and Visual Basic?
I'd look for someone who has coded C or C++. These languages provide
powerful tools for heavy duty memory management--namely, pointers. Both
variable and function pointers will be used extensively by experienced C
and C++ programmers. I'd compare to something in VB, but pointers are not
externalized to programmers in that language. The concept of pointers is
relatively easy to understand--a pointer is a variable that contains the
memory address of another variable or function. However, interpreting and
documenting code with little prior knowledge or experience with pointers
will be difficult without extensive reading/mentoring. It's one thing to
document a for/next or do/while loop ... it's entirely another thing to
follow a pointer to a pointer to a pointer to a function pointer.
In addition, C++ is an OOP, which defines another skill set that is not
necessarily intuitive nor easy to learn.
Despite my seemingly discouraging words, I've never been one to discourage
anyone from learning or trying something new. Talk with your programmers to
get an idea of the complexity of the code--does it make extensive use of
mathematical principles--recursion, statistics, linear analysis, etc.--that
would be common in intensive number crunching apps like graphics,
engineering, or encryption? Are you equipped to deal with that? Do the
applications do alot of database input/output or network connectivity? Are
you equipped to deal with that? Be informed. Make your decision based on as
much info as you can obtain within your time constraints.
Good luck! And let us know what you decide!
Regards...Kris
--------------------------
kolberg -at- actamed -dot- com
kris -at- olberg -dot- com
