Short but to the point
- “Documenting Networks,” Asterisk (published by
ACM SIGDOC), vol. 11, no. 3, September 1985. Rough guidelines based on
experience.
- “If They Don’t Read You—Try This,”
Technical Communication, vol. 33, no. 2, Second Quarter 1986. A
satire with some serious suggestions for the writer’s work
environment.
- “Opening Passage: A New Look at the System Documentation
Problem,” IEEE Transactions on Professional
Communication, vol. PC-29, no. 4, December 1986, pp. 3-10. A stab
at finding an objective basis for analyzing the problems of computer
documentation.
- “Essential Computer Training for Writers of Software
Documentation,” Proceedings of the 35th International
Technical Communications Conference, Philadelphia, Pennsylvania,
May 10-13, 1988, pp. RET-143—RET-146. Brief illustrations of the
principles of computer design that are relevant for writers, and some
preliminary proposals for training in both academic and job-related
settings.
- “Where Computers are Taking Us in the Education Field”
(with Ernest Kahane), in Christine M. Shea, Ernest Kahane, and Peter
Sola, eds., The New Servants of Power: A Critique of the 1980s
School Reform Movement, Greenwood Press, 1989, pp. 67-74. A social
and political critique of training and human development within the
computer industry.
- “The Hidden Effects of Computer Engineering on User
Documentation,” in Thomas T. Barker, ed., Perspectives on
Software Documentation: Inquiries and Innovations, Baywood Press,
1991. Histories and examples of the software principles at the base of
my method.
- “Reckoning With Computer Design: A New Discipline for
Technical Writers in the Computer Field,” unpublished (and
perhaps unpublishable) draft. A detailed analysis of the effects that a
developing team’s understanding of computer design has on
computer manuals, plus a use of this analysis to critique reference
manuals, user-oriented documentation, and modern on-line media such as
hypertext.
- “Sentence First, Verdict Afterward: Finding the Prerequisites
for Good Computer Documentation” (with Kathleen Ferraro), ACM
SIGDOC ’89 Proceedings. A description of the model
recommended for computer documentation and review.
- “Examples or Descriptions? Have it Both Ways, With Annotated
Examples,” Technical Communication, vol. 37, no. 4,
November 1990, pp. 363-365. Brief description of a type of programming
example that uses call-outs, thus improving readability and helping the
reader focus on key points.
- “Writing at the User Interstices,” Boston
Broadside, January 1991. A brief article warning that
writers’ work increasingly becomes a matter of updating older
books or filling in gaps left by standard computer literature, and that
this activity requires a very different attitude toward manuals and a
broader learning style.
- “Do We Dare to Free Our Computer Users?” Technical
Communication, Technical Communication. A plea for writers to take
a broader view of the systems they document, and a more responsible
attitude toward their readers, based on an exploration of the realities
of computer use and development. My last article written for technical
writers; thereafter I devoted my efforts to software engineers.
- “Methods and Mechanics of Creating
Reliable User Documentation,” Proceedings of the 1991
Pacific Northwest Software Quality Conference, Pacific Agenda,
Portland, Oregon, 1991. An introduction to the idea of formally
reviewing documents, accompanied by actual processes and internal
documents that have been used to create documents in this manner,
written for software engineers.
- “Documentation of Programming Tasks as an Aid to Adoption of
a Standard,” StandardView, vol. 1, number 2, ACM,
December 1993, pp. 42-48. An argument for standards committees to
develop the raw materials for programming guides using my method.
Author’s home page