SOFTWARE IN PRACTICE

LOGIN / REGISTER

• Home
• Services
  • Capability Statement
  • Requirements Specification
  • Design
    •    Control System
    •    Database
  • Testing
  • Project Management
  • Quality Management
  • System Safety
  • Configuration Management
  • Verification & Validation
  • Tender Preparation
  • Mentoring
  • Training
• Workshops
  • Software Quality
  • Software Project Management
  • Software Requirements
• Blog
• Resources
  • Design
    • Standard: System Architecture Specification
  • Case Study
    • Saving Obamacare
    • Saving Obamacare Analysis
  • References
  • Requirements
    • Standard: Software Requirements Specification
    • Checklist: Requirements Capture Learning Needs
  • Software Engineering
    • Introducing Software Engineering
  • Story Theory
  • System Safety
    • 10 Minute Guide to IEC 61508
• Videos
  • Project Management
    • The Project Planning Process
    • Risk Management Planning
    • What is a Work Breakdown Structure?
    • The WBS Development Process
    • Fleshing out the WBS
    • Planning Project Services
    • Earned Value Management
  • Quality
    • Does Quality Matter?
    • Quality Management System Framework
    • Quality Management System Architecture
  • Requirements
    • Specifying Software Requirements
  • Systems Engineering
• Forums
  • Forum Summary
  • The Rant
  • The Read
  • The Risk
• Glossary
  • A
    • Activity
    • Architecture
    • Architectural Views
  • B
    • Baseline
  • C
    • Change Proposal
    • Change Request
    • Chunking Principle
    • Compliance
    • Configuration
    • Configuration Audit
    • Configuration Control
    • Configuration Control Board
    • Configuration Identification
    • Configuration Item
    • Configuration Item Register
    • Configuration Management
    • Configuration Status Accounting
    • Conformance
  • D
    • Definition
    • Deliverable
    • Design Entity
    • Design View
  • E
    • Earned Value Management
  • F
    • Functional Safety Management
  • G
    • Glossary
    • Goal
  • H
    • Hazard
    • Hazard Analysis
    • Hazard Discovery Techniques
    • Hazard Log
  • I
    • Influence
    • Interface
    • Interface Control Document
    • Interface Management Plan
  • J
    • Joint Application Design
  • K
    • Knowledge Management
  • L
    • Learnability
  • M
    • Management by Deliverables
    • McCabe Cyclomatic Complexity
    • Mentoring
    • Milestone
  • N
    • Non-conformance
    • Non-conformance Report
  • O
    • Objective
    • Objective Evidence
    • Ontology
  • P
    • Patterns
    • Philosophy
    • Precedence Diagram
    • Process
    • Project Planning
    • Project Services
    • Prototype
  • Q
    • Quality Assurance
    • Quality Control
    • Quality Improvement
    • Quality Management
    • Quality Management Framework
    • Quality Management System Architecture
    • Quality Planning
    • Quality Objectives
    • Quality Policy
  • R
    • Rationale
    • Requirements Elicitation
    • Requirements Patterns and Ontologies
    • Risk
    • Risk Management Planning
  • S
    • Safety (Software/System)
    • Scope
    • Software Engineering
    • Software Testing
    • SRS: Software Requirements Specification
    • SyAS: System Architecture Specification
  • T
    • Task
    • Tender Preparation
    • Testing
    • Test Documentation
    • Traceability Analysis
    • Traceability Matrix
    • Training
  • U
    • Use Case
  • V
    • Verification & Validation
  • W
    • WBS - Work Breakdown Structure
    • WBS - Project Services
  • Y
  • Z
• Contact

Writing a "Good" Definition

To learn anything you need to understand the concepts that surround and inform the focus of your learning. Technical writing often disappoints when complex concepts are referred to but never explained leaving the reader alienated from the entire learning experience. Good concept definitions therefore facilitate and speed learning and engage your audience in the learning process.

You can judge the quality of a concept definition by evaluating its impact on the reader. A good definition helps your audience:

• Generalise by correctly identifying new examples of that concept
• Discriminate by correctly separating those things which may be closely related to the concept but are not the concept itself
• Value the concept by understanding where the concept is relevant to your reader's situation
• Apply the concept to real-world problems by following practical courses of action.

When writing a definition consider using some of the following devices:

• Aliases. Any given concept may have many names. To orient your audience name all commonly used aliases and pick a primary name. To avoid confusion use the primary name exclusively in your concept definition. See Functional Safety Management Aliases
• Contrasting concepts. If the concept is likely to be confused with one or many other concepts, compare and contrast them and identify how they are different. See Contrasting Verification and Validation
• Functional definition. Describe concepts in terms of the way they are used. See Configuration Identification, Influence
• Genus-species. Define a concept by the larger groups or classes to which it belongs. For example: genus - a barcode scanner is a type of pattern recognition device, species - that uses a laser beam to detect and read universal product codes. See also Chunking Principle
• Story. Tell a story that illustrates the concept's application to real life. See Configuration Identification Why Configuration Identification Is Important. Don't be afraid of being outrageous. Learning is an emotional experience. See Scenario 4 - The Apocalyptic Test of an Effective Configuration Identification Strategy
• Critical attributes. Describe attributes that must be recognised to discriminate one concept from another. See Contrasting Verification and Validation
• Example. Provide examples of the concept. See Examples of Project Goals
• Non-example. Provide an example that is close but does not illustrate the concept. See Objective Evidence, A Non-example of Objective Evidence

Configuration identification. Most programmers would rather stick a fork in their eye than reflect on the importance of configuration identification in a software project. But be aware that faulty configuration identification processes are a common cause of project failure. If you want to avoid carnage on your project get across the practical wisdom that this discipline represents. Learn more.