John E. Darrow -- Documenting Java and C++ -- Course Descriptions
Courses: Documenting Java, Documenting C++

Related links:

Instructor

John E. Darrow [ resumé | main page ]

Description

Many companies are developing new or rewriting existing applications in Java or C++ and need technical communicators who can provide documentation for such applications. In most cases, it is enough for a technical communicator explain to the average reader how to use the Java or C++ application (for example, to document its graphical user interface). Companies have style guides for such simple tasks.

But what if the intended audience is programmers who need to know the command line syntax of the program or the API of the program? What if that audience needs to understand the parameters of a Java applet for use in a web page? (See FAQ for definitions of each.) The technical communicator needs certain vocabulary and technical knowledge to provide effective documentation for such an audience.  And programmers prefer to work with knowledgeable technical communicators.

How is the technical communicator to get such knowledge? Almost all Java and C++ books and courses are created BY programmers FOR programmers, a significant mismatch for the needs of technical communicators, yet many technical communicators go to such programming classes (and, not surprisingly, are overwhelmed).

These courses, in contrast, were designed FOR technical communicators BY a software technical communicator and programmer. He knows what programmers consider to be effective documentation (he has to read such documentation when programming) and helps the student understand the writing task from both writing and programming perspectives. He knows what technical communicators do and do not need to know about programming in order to dig through Java or C++ code and extract key information for an effective first draft of API documentation.

It is the instructor's strong belief that a course of this quality and focus is a must for any technical communicator who is serious about software technical communication. Have students agreed? Overwhelmingly, yes. Read their comments for yourself.

Objectives

Upon completion of either course, the participant will be able to:

  • Review code and identify "classes" and their members and know which of those members he or she should describe in API documentation
  • Describe the difference between a class and an instance
  • Describe the four main things a technical communicator will need to document about a function (C++) or a method (Java)
  • Prepare draft API reference documentation directly from the code
  • Describe the implications of inheritance and overloading
  • Describe the implications of the static, const (C++) and final (Java) and the access modifiers public and private
  • Demonstrate proper formatting of code samples, such as breaking or rewriting code lines that are longer than a document's margins allow, and repairing indentation
  • Document the command line interface of an application
  • (Java) Describe the difference between applets and applications and know what it means to "document an applet"

Intended audience

These courses are ideal for:

  • all levels of technical communicators who need or want to document Java or C++ for a programming audience
  • documentation managers who want to pursue a Java or C++ documentation project and need to assess the skill level and knowledge required of their technical communicators
  • those considering a career change into technical communication
  • anyone wishing to be solid in object-oriented concepts and Java- or C++- specific terminology

The instructor paces the class according to the needs of those newest to the topic. Plenty of time is allowed for both beginning and advanced questions, though the instructor reserves the right to cut off tangents that do not help the class as a whole.

Duration

Documenting Java: two full day sessions

Documenting C++: two full day sessions

Combined course (Java and C++): three full day sessions

See related FAQ items.

Prerequisites

No prior programming experience is required. However, this course is packed with technical concepts and the serious student should come prepared to dive into these topics and have the guts to ask questions when not clear on the subject matter.

Methods

Lecture, in-class exercises and a final. See related FAQ item.

Suggested follow-on course

Students who have completed either Documenting API course are ready for an introductory course in object-oriented programming. Such a course can give the technical communicator a better understanding of the needs of programmers and of the fundamental concepts and issues of programming in an object-oriented language.

Consider the introductory-pace Java Programming course, which exercises and builds upon the key concepts presented in the documentation courses.

Also available is a course on Reading Java Code, a survey course based on the list of topics of the intensive-pace Java Programming course, helping the technical communicator learn about the most commonly used keywords, utility classes and broad concepts in Java. Write for more information.

Fee

One programming language (two days): $2000/class or $400/student, whichever is greater, plus materials and travel expenses, if appropriate.

Both programming languages (three days): $3000/class or $600/student, whichever is greater, plus materials and travel expenses, if appropriate.

Class Size

35 students maximum. See related FAQ item.

Room requirements

One very large whiteboard or two small whiteboards. No computers needed. No overhead projector needed.

John E. Darrow 
Other John Links