Extended definitions


Published on

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

Published in: Education, Technology, Business
  • Be the first to comment

No Downloads
Total views
On SlideShare
From Embeds
Number of Embeds
Embeds 0
No embeds

No notes for slide

Extended definitions

  1. 1. Technical Writing: Extended Definitions <ul><li>Effective Communications for Programmers and the Grammatically Challenged </li></ul>
  2. 2. <ul><li>“ Anything worth doing, </li></ul><ul><li>is worth doing right” </li></ul><ul><li>- Hunter S. Thompson </li></ul>
  3. 3. Poor Documentation <ul><li>Poor documentation can cost money: </li></ul><ul><ul><li>in customer support calls </li></ul></ul><ul><ul><li>wasted engineering efforts during collaboration </li></ul></ul><ul><ul><li>missed deadlines </li></ul></ul><ul><ul><li>legal issues (project scope, deliverables) </li></ul></ul>
  4. 4. Why? <ul><li>In large compartmentalized organizations, software developers are tasked with writing more documentation. </li></ul><ul><li>Developers are required to write more software specifications, test plans, and API documentation. </li></ul><ul><li>Self-documenting code (doxygen) </li></ul>
  5. 5. Extended Definition <ul><li>Extended Definition defines and explains a single term, concept or object </li></ul><ul><li>Pins down the meaning of a specific word, or defines an abstract concept </li></ul><ul><li>Goes deeper than a simple dictionary definition. </li></ul>
  6. 6. Planning <ul><li>What is the concept to be defined? </li></ul><ul><li>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? </li></ul><ul><li>What is the purpose? Are you documenting a class or system? </li></ul>
  7. 7. 3 Simple Steps <ul><li>Tell readers what term is being defined. </li></ul><ul><li>Present clear and basic information. </li></ul><ul><li>Use facts, examples, or anecdotes that readers will understand. </li></ul>
  8. 8. Introduction <ul><li>Introduction </li></ul><ul><ul><li>Include the standard definition. You may want to include the traditional or dictionary definition to provide a basis for your extended definition. </li></ul></ul><ul><ul><li>You may want to open with a contradictory image to illustrate what the term is not. </li></ul></ul>
  9. 9. Introduction <ul><li>Term to be defined </li></ul><ul><li>Sentence definition of the term </li></ul><ul><li>Reason(s) for giving a more detailed definition </li></ul><ul><li>The kinds of additional information that will be used to extend the definition </li></ul>
  10. 10. Patterns <ul><li>Classify. Divide subject into types, and describe each type. </li></ul><ul><li>Compare and Contrast. Show how the subject is like/unlike something. </li></ul><ul><li>Illustrate. Give examples or narrate incidents. (use cases) </li></ul><ul><li>Cause/Effect. Analyze why something happened. </li></ul>
  11. 11. Patterns <ul><li>Negation. Describe what it is NOT. What are the limitations. </li></ul><ul><li>Analysis: Divide the subject into parts and define each part separately. </li></ul><ul><li>Anecdotal illustration. Narrate illustrations that can clarify a group, theory or object. </li></ul>
  12. 12. Patterns <ul><li>Narrative: a story that helps illustrate the definition. </li></ul><ul><li>Effects: Discuss the uses and consequences (both positive and negative) of the subject. </li></ul><ul><li>Origin and Cause: Where did the subject come from? What is the background information? History? </li></ul>
  13. 13. Conclusion/Transition <ul><li>Wrap it up. </li></ul><ul><li>Reference back to the opening </li></ul><ul><li>Reflection: Include a comment about the term or summarizing statement. </li></ul>
  14. 14. Example <ul><li>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. </li></ul>
  15. 15. Example <ul><li>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. </li></ul><ul><li>briefly explain the classifications... </li></ul>