Software Development Tech Writing

[Patrick McCarthy <PTM123 -at- AOL -dot- COM>]

                                                                      2/21/96


  Dear Writers,


 I was really pleased to see some discussion about object-oriented
programming.
 However, it is also important to know what a technical writer will be
responsible for
 in a software development environment. For anyone interested, I am including
a copy
 of a paper I wrote for the Chicago STC regarding software development tech
writing.


                                               Regards,

                                               Patrick McCarthy
                                               Chicago, IL


Documenting the Software Development Process: The Shape
of Things to Come


                      By Patrick McCarthy


The 90s has seen software development become the dominant force
in information technology. As computer and networking
technologies advance, the software required to drive these
entities has become increasingly sophisticated. Just as user
documentation has grown in complexity and scope, software
development documentation brings with it new requirements and
challenges. It is the purpose of this article to discuss the role
of the technical writer and documentation development as they
relate to the software development process.

Overview of Software Development Technical Writing

Imagine that you are the manager of a software development team.
You have 15 people working for you. Some are developers, system
testers, and system administrators. You report to a director who
in turn reports to a vice president. Both are very interested in
the 8 million dollars you are spending to develop that great
software package. You must make presentations, write progress
reports, and produce technical proposals so that management and
clients stay happy. You must also document each software process
and task to ensure continuity in the event someone leaves. The
pressure is on! The board wants to  see a design document, a
programmers style guide to show that you are producing structured
code, and a detailed description of the development environment
(hardware, operating system, and CASE tools). Who is going to
produce such documents? The software technical writer.

To begin with, one should not confuse the documentation of an
application software package with software development
documentation. They are two separate tasks. It is one thing to
produce manuals for an existing software package (user guides,
help screens, and reference manuals) and quite another to
describe the hardware, operating systems and programming
languages used to develop it.

There are many facets to software development writing. To avoid
being overwhelmed by this subject, it is important for a writer
to study the major job functions of software development. Once
you understand the basic differences between a software
developer, a systems tester, and a system administrator, the
documents produced in this situation will begin to make sense.
The following paragraphs describe some of the major functions in
software development:


     Software Developer- Develops a specific part or feature of a
     software package according to a design requirement. The
     developer is responsible for the design and in some cases
     the writing of source code.

     System Test/Integrator-Takes the individual programs written
     by developers and debugs them. Tries to get all the pieces
     to function as a single software package. Also runs software
     on the "target" platform (ie the hardware platform that the
     customers will use). System test may also produce a
     "sustaining engineering" guide for maintaining a software
     package after its initial release.

     CASE Tool Expert-A CASE tool (Computer Aided Software
     Engineering) is a software development tool that helps the
     programmers write source code, manage files, find problems
     etc. This individual will be the resident expert with this
     program so that other programmers can get help and guidance
     during the development process.

     System Administrator- The system administration function is
     not directly concerned with the development of the software
     end product. It administers and maintains the environment in
     which software is developed. This function is directly
     responsible for maintaining the computer hardware, operating
     system (OS), and LAN. Some of the major tasks involved with
     system administration are system restoration and backup,
     providing connectivity from one computer system to another,
     and accessing outside networks.


Upon entering a software development group, the writer should
learn as much as he or she can by reading the Detailed Design
Document and other source material pertinent to the high-level
design and functionality of the software package. Once a solid
foundation has been established, the writer should examine the
individual job functions (software developer, system test etc)
and determine which function can provide the required information
for the task at hand. For example, if the writer needs flow
charts and process call routines, it would be logical to check
with the CASE tool expert and software developers. Their
functions would most likely produce such material. Likewise, if
the writer were required to produce a manual concerning the
target platform for the software package, system test would have
much of the material in their test plans.


 In some cases, the process of developing documents in a
software development environment is radically different from
traditional methods . Carl Kalbfleisch, a Senior Software
Engineer at Octel Network Services in Dallas, Texas described
this scenario for the development of a Detailed Design Document
(the document that describes the individual pieces of the
program), "The development of the Detailed Design Document
involves extracting certain comments (descriptive text in the
actual source code) from the individual programs and
converting them to HTML or MS Word. In order to complete this
task, a writer must be familiar with the CASE tool such as
SCCS to edit the source code so this process may be
performed".



Skill Levels and Subject Matter

Writing tasks vary in a software development environment in terms
of skill and subject matter (see Table 1). Situations differ and
the proportion of writing skills to software skills changes. For
example, a user guide for Windows may require the writer to have
25% software skills and 75% publications skills. The author of a
programmers style guide may need 75% software skills and 25%
publications skills. Certainly, this is a subjective analysis but
indicates how skill levels and combinations vary from task to
task. Many job requirements in software development writing
indeed require a "hybrid" or a unique set of skills.

Also, it is important not to become intimidated by the
technologies of software development. In "Preparing to Document
an Object-oriented Project", Berry, Mobley, and Turk write, "Even
if you don't have a programming background, don't panic. In some
ways, object-oriented programming is easier to learn than
traditional programming". The task of a writing in this situation
is to understand a variety of technologies and processes-not to
perform them all. As software development technologies advance,
the user interface generally becomes more intuitive. For example,
the Windows operating system is more user-friendly than the DOS
operating system because the user can navigate by icons rather
than line commands. In much the same manner, the tools for
software development have become more user-friendly, making them
easier to grasp at a high level for the technical writer.



Redefining The Role Of The Technical Writer

As corporations struggle to reengineer themselves and technology
changes at an accelerated pace, the role of the technical writer
changes too. In software development, the writer is part
programmer, part document developer. Gone are the days of the
technical communicator being a separate function from the
development community. In many of these job descriptions, the
software technical writer not only works closely with the
development team but is a part of that team. Why? There are many
reasons.




First, there is simply too much knowledge and too little time for
an outsider to come in and write documents during a development
cycle. Software development documentation requires an intimate
knowledge of the subject matter and day-to-day interaction with
the technical staff. Secondly, the traditional publications group
with writers, illustrators, and managers is not needed in many
cases.  It is more efficient and profitable to have a writer in
the technology "workgroup" than to deal with engineers and
developers as an "outsider". In his book, "DeskTop Magic", John
Wood discusses the advantage of the "workgroup" philosophy:

     One lesson learned was that successful projects often
     involved small groups, combining authors and technical
     personnel. Team members interacted well and understood each
     others goals. By contrast, projects that did not do well
     demonstrated poor interaction by writers, illustrators,
     and engineers confused as to whose role it was to do what.

Another reason writers may be found in a software development
group is that they are not "just writers" anymore. They are
developers in their own right, producing documents for a highly
sophisticated audience. Andrew Davis, president of Synergistech
Communications (a San Francisco based agency specializing in the
placement of staff and contract technical writers) made the
following comments when asked about the role of technical writers
in high tech environments:


   * The majority of lucrative documentation work is with
     client/server software development companies, and these
     companies look for solid experience with FrameMaker, UNIX,
     relational databases, C and C++, and/or networking
     technology. They distrust writers whose attitude is that the
     writer should be a stranger to the technology so that he or
     she can represent it more objectively.

  * For writers without specifically relevant technical
    expertise, end-user software tech pubs (now often called "GUI
    doc") jobs pay as much as 30% less than jobs writing
    documentation for technical audiences such as developers and
    systems or network administrators.

The bottom line is simple. It is no longer adequate to be a
"publications skills only" writer in high tech environments. The
job market is demanding some knowledge of computer hardware,
software technology, and networking. The writer must adapt to
this situation by upgrading his or her technical skills and
modify the writing style for a technical audience.




Job Descriptions For Software Technical Writers

You will notice that each of the four job description relates to
a specific function of the software development process or a
combination of them. You will also notice that these positions
are not strictly for individuals with computer science
backgrounds. Many require excellent writing skills in addition to
a host of technical requirements. These descriptions were taken
from a variety of sources including the internet, contract
employment agencies, and the STC BBS. They represent a broad
range of geographical locations and companies. Many of these jobs
are quite demanding in terms of requirements but the rewards are
there. As Andrew Davis put it, "the software development
documentation markets are poorly served by all but a few of the
most technically accomplished writers, and that those
sufficiently technical to do this kind of work are easily able to
earn six figures as an independent contractor, or $80K as a staff
employee".


Description #1:


Job Title: Senior Software Technical Writer (Software Development
Documentation)

Description: Writer to develop and maintain software development
documents. Must be able to present complex information to a
technical audience with efficiency and precision. Should be
familiar with SGML authoring tools and have a basic understanding
of the software development process (what each function does and
the basic processes involved). Should also be familiar with
online documentation development.


Qualifications:

-BA/equivalent experience
-Must have at least 3-5 years technical writing experience in a
 C/UNIX environment.
-Knowledge of Standard Generalized Markup Language (SGML) tools
 and document modeling.
-Be familiar with the basic concepts of Object Oriented
 Programming.
-Be familiar with a Graphic User Interface (GUI) design under
 UNIX or Windows NT.
-Be familiar with creating online documentation.
-FrameMaker or Interleaf authoring tools.
-Documentation distribution through CD-ROM.



Description #2:

Job Title: Senior Software Technical Writer (Operating System,
Software Development)

Description: Writer to support the documentation needs of a
company which produces mass storage capability for businesses.
The individual will be involved in all areas of document
development from documentation plans, task analysis, outlines,
verification and review. Will work closely with software
developers and marketing teams.

Qualifications:

-BA/equivalent work experience.
-5-7 years technical writing experience with at least 3 years in
 a UNIX environment.
-Knowledge of UNIX system file managers and internals.
-Ability to use Interleaf or FrameMaker.
-Ability to work independently as part of a software development
team.



Description #3:

Job Title: Senior Technical Writer (System Administration)

Description: Writer to support documentation efforts for system
and network administration. Must be familiar with UNIX and basic
networking concepts (TCP/IP). Will document procedures for
interfacing to customer networks. Will develop Help Guide for
high-level solutions to frequently asked questions.

Qualifications:

-BS in Computer Science or Technical Writing.
-Solid understanding of UNIX (file management, shell scripts).
-Familiar with network configuration and client/server
technology.
-Demonstrated ability with authoring tools
(Interleaf/FrameMaker).


Description #4:

Job Title: Senior Software Technical Writer (Software
Development)


Description: Writer to be part of a dynamic software development
team which will develop a real-time software package on SUN
workstations for a target platform of the Solaris operating
system on personal computers. Will document the process of
porting source code from development platform (SUN/UNIX) to the
target platform (Solaris/PC).

Qualifications:

-BS in Computer Science or Technical Writing with significant
 course work in computer science
-Understanding of ANSI C (C++ preferred)
-Ability to document event-driven programming and callback
 routines.
-Solid understanding of UNIX (file management, shell scripts).
-Ability to document cross-platform issues (SUN/UNIX to
 Solaris/PC)
-Experience writing applications with Graphical User Interfaces
-Demonstrated ability with authoring tools
(Interleaf/FrameMaker).


Conclusion

Software development documentation and the technologies
associated with it present technical communicators with new
challenges and job opportunities in the 90s and beyond. This
article was written to bring some attention to an interesting and
upcoming discipline. After reading this article, I hope that many
writers ,unfamiliar with this subject, will see software
development documentation, not as an obscure job function but as
a mainstream profession.


Acknowledgements:

The author would like to acknowledge the following individuals
for assistance in preparing this article:

Andrew Davis
President
Synergistech Communications
1824 Byron Avenue
San Mateo, CA 94401
adavis -at- netcom -dot- com



Carl Kalbfleisch
Senior Software Engineer
Octel Network Services
Dallas, TX
cwk -at- pic -dot- net


REFERENCES:

1. Internet news groups, March and April 1995

2. Contract Employment Weekly, various employment advertisements,
March and April 1995

3. Berry, Mobley, and Turk. 1994 Journal of the Society for
Technical Communication. Fourth Quarter (November). 643-651

4. Wood, John. 1995 "Desktop Magic", New York, New York: Solomon
Press