Extended definitions

This is part of a series on technical writing for programmers. This one focuses on the extended definition concept.

1. Technical Writing:
Extended Definitions
Effective Communications for Programmers and the
Grammatically Challenged

2. ““Anything worth doing, Anything worth doing,
is worth doing right”is worth doing right”
- Hunter S. Thompson- Hunter S. Thompson

3. Poor Documentation
•Poor documentation can cost money:
•in customer support calls
•wasted engineering efforts during
collaboration
•missed deadlines
•legal issues (project scope, deliverables)

4. Why?
•In large compartmentalized organizations,
software developers are tasked with
writing more documentation.
•Developers are required to write more
software specifications, test plans, and API
documentation.
•Self-documenting code (doxygen)

5. Extended Definition
•Extended Definition defines and explains a
single term, concept or object
•Pins down the meaning of a specific word,
or defines an abstract concept
•Goes deeper than a simple dictionary
definition.

6. Planning
•What is the concept to be defined?
•Who is the intended audience? Is this for
general audience or specific/specialized
audience that will know technical terms
and will not require further definition?
•What is the purpose? Are you
documenting a class or system?

7. 3 Simple Steps
•Tell readers what term is being defined.
•Present clear and basic information.
•Use facts, examples, or anecdotes that
readers will understand.

8. Introduction
•Introduction
•Include the standard definition. You may
want to include the traditional or
dictionary definition to provide a basis
for your extended definition.
•You may want to open with a
contradictory image to illustrate what
the term is not.

9. Introduction
•Term to be defined
•Sentence definition of the term
•Reason(s) for giving a more detailed
definition
•The kinds of additional information that will
be used to extend the definition

10. Patterns
•Classify. Divide subject into types, and
describe each type.
•Compare and Contrast. Show how the
subject is like/unlike something.
•Illustrate. Give examples or narrate
incidents. (use cases)
•Cause/Effect. Analyze why something
happened.

11. Patterns
•Negation. Describe what it is NOT. What
are the limitations.
•Analysis: Divide the subject into parts and
define each part separately.
•Anecdotal illustration. Narrate illustrations
that can clarify a group, theory or object.

12. Patterns
•Narrative: a story that helps illustrate the
definition.
•Effects: Discuss the uses and consequences
(both positive and negative) of the subject.
•Origin and Cause: Where did the subject
come from? What is the background
information? History?

13. Conclusion/Transition
•Wrap it up.
•Reference back to the opening
•Reflection: Include a comment about the
term or summarizing statement.

14. Example
A singleton is a design pattern that restricts
instantiation of a class to one object. This is
useful when exactly one object is necessary to
coordinate actions across an entire system.

15. Example
In C++, there are several ways to create
singleton: class defined as const global variable,
a class with all static members, and a class
instantiated through a static method which
returns a pointer or reference the allocated
class object.
briefly explain the classifications...