Cover image for Telling Stories: A Short Path to Writing Better Software Requirements

Telling Stories: A Short Path to Writing Better Software Requirements

Author Ben Rinzler
Release Date: 2009/03/01
ISBN: 9780470437001
Topic:
0%
14
Chapters
0-1
Hours read
0k
Total Words
    Start Reading Now    
       Add to Wishlist       
View table of contents

Book Description

From System Designers to Top Management, Everyone loves a good story

Once upon a time, it was well understood that stories teach better than plain facts. Why then are most software requirements documents a baffling hodge-podge of diagrams, data dictionaries, and bullet points, held together by little more than a name and a staple? Telling Stories teaches you to combine proven standards of requirements analysis with the most ancient and effective tool for sharing information, the narrative. Telling Stories simplifies and refines the classic methods of Structured Analysis, providing organization, design, and old-fashioned writing advice. Whether you?re just getting started or an experienced requirements writer, Telling Stories can help you turn dull, detailed material into an engaging, logical, and readable story, a story that can make the difference for your project and your career.

  • Learn why readers believe and remember what they learn from stories

  • Work with team members to gather content, tell their stories, and win their support

  • Use stories to find every requirement

  • Create diagrams that almost tell the story on their own (while looking clear and professional)

  • Explain everything important about a process

  • Use precise language to remove the ambiguity from requirements

  • Write a forceful executive summary that stands on its own and sells a project to senior management

  • Summarize often to keep the reader focused on key issues

  • Structure the document so every part has a clear place and purpose

Table of Contents

  1. Copyright
  2. About the Author
  3. Credits
  4. Acknowledgments
  5. Introduction
  6. 1. Telling Stories
    1. 1.1. What Must We Do?
    2. 1.2. Why Do We Learn Better From Stories?
    3. 1.3. How Do Story Elements Relate to Requirements?
    4. 1.4. What Are Software Requirements, and Who Are They For?
      1. 1.4.1. Are Software Requirements Different from Business Requirements?
    5. 1.5. Why Projects Collapse (Without Detailed Requirements)
    6. 1.6. Why Have We Turned from the Path of Righteousness?
    7. 1.7. Can Stories Get Us Back on Track?
    8. 1.8. Making Structured Analysis into a Story
    9. 1.9. Who Should Do This Work?
    10. 1.10. Summary
  7. 2. The Language of Your Story
    1. 2.1. Clarity
      1. 2.1.1. Use Words Your Reader Understands
      2. 2.1.2. Careful with It
      3. 2.1.3. Don't Make Up New Terms
      4. 2.1.4. Write Short Sentences with a Clear Actor and Action
      5. 2.1.5. Clear and Concise
    2. 2.2. Precision
      1. 2.2.1. Vague Requirements
      2. 2.2.2. Ambiguous Requirements
      3. 2.2.3. Overly General Requirements
      4. 2.2.4. The Dangers of Technology Words
      5. 2.2.5. Imprecise, Buzzword-Laden Management-Speak Summaries
      6. 2.2.6. A Paragraph Is a Short Subject
    3. 2.3. Using a Consistent and Appropriate Level of Detail
    4. 2.4. Summary
  8. 3. Drawing Pictures
    1. 3.1. Why Data Flow Diagrams?
    2. 3.2. Data Flow Diagram Elements
    3. 3.3. Basic Rules
      1. 3.3.1. A Process Cannot Create Data
      2. 3.3.2. Data Must Come from an Identified Source
      3. 3.3.3. Data Cannot Move or Change by Itself
      4. 3.3.4. A Diagram Must Begin and End with a Data Store or an External
      5. 3.3.5. Processes Are Actions, Not Entities
    4. 3.4. Summary and Detail Diagrams
      1. 3.4.1. Do Not Go More Than Three Levels Deep
    5. 3.5. About Creating Rough Diagrams
    6. 3.6. Guidelines for Design Clarity
      1. 3.6.1. Start at the Top and Flow Down and to the Left
      2. 3.6.2. Align Everything
      3. 3.6.3. Make Things the Same Size
      4. 3.6.4. Distribute Elements Consistently
      5. 3.6.5. Connect at Only Four Points
      6. 3.6.6. Use Only Straight Lines and 90-Degree Angles
      7. 3.6.7. Consider the Composition and Orientation
      8. 3.6.8. Use the Same Font and Sizes
      9. 3.6.9. Group Related Items and Annotate Diagrams to Add Meaning
    7. 3.7. Other Types of Diagrams
      1. 3.7.1. Architecture, Network, and Component Diagrams
      2. 3.7.2. UML Diagrams
      3. 3.7.3. Swim Lanes
    8. 3.8. Summary
  9. 4. Explaining Processes and Finding Requirements
    1. 4.1. Naming Processes
    2. 4.2. Success Criteria
    3. 4.3. Started by
    4. 4.4. Results of
    5. 4.5. Elements of
    6. 4.6. Actions
      1. 4.6.1. Exception Handling
      2. 4.6.2. Indenting Paragraphs That Explain Exceptions
      3. 4.6.3. Listing Possible Exceptions as Indented Bullet Points
      4. 4.6.4. Adding an Indented Table with Exceptions and Their Outcomes
    7. 4.7. Cross-References to Other Processes
    8. 4.8. Extracting Requirements
      1. 4.8.1. Language in Requirements
      2. 4.8.2. Numbering Requirements
      3. 4.8.3. Data Requirements in Process Descriptions
      4. 4.8.4. Considering Business Rules and Nonfunctional Requirements
    9. 4.9. Options for Structuring Diagrams and Text
      1. 4.9.1. A Formal, Tabular Approach
      2. 4.9.2. A Simpler Prose-Based Approach
      3. 4.9.3. An Integrated Diagram and Requirements
    10. 4.10. Adding Diagram and Section Introductions
    11. 4.11. Summary
  10. 5. Finding and Structuring the Content
    1. 5.1. You Are a Very Important Team Member
    2. 5.2. Building Rapport with the Project Team
    3. 5.3. Capturing the Critical Information
      1. 5.3.1. What Are the Business Purposes of the System?
      2. 5.3.2. What Are the Main Elements of the System?
      3. 5.3.3. What Does the System Do?
      4. 5.3.4. What Is the System Doing Well Now?
      5. 5.3.5. What Is the System Doing Poorly?
      6. 5.3.6. What Must the System Continue to Do?
      7. 5.3.7. What External Data Does the System Rely On?
      8. 5.3.8. What Data Must the System Provide to Other Systems?
      9. 5.3.9. What Do We Hope the New System Will Do Better
      10. 5.3.10. Other Lists
    4. 5.4. Writing the Outline
      1. 5.4.1. What to Include, What to Leave Out
      2. 5.4.2. A Generic Outline
      3. 5.4.3. An Agile Outline
      4. 5.4.4. A Robust Outline
    5. 5.5. Summary
  11. 6. Creating the Body of the Document
    1. 6.1. Is Documenting the Current State Really Necessary?
    2. 6.2. Go Back to the Team
      1. 6.2.1. Present Draft Diagrams
      2. 6.2.2. A Sample Project Inventory
      3. 6.2.3. Consider Context
      4. 6.2.4. Complete a Single Process
      5. 6.2.5. Using Cross-References
    3. 6.3. Writing the Future State
      1. 6.3.1. Carrying Requirements Forward
      2. 6.3.2. Don't Design Solutions
    4. 6.4. Checking for Completeness
      1. 6.4.1. Prototypes
    5. 6.5. Reference Material After the Story
      1. 6.5.1. Gap Analysis
      2. 6.5.2. Requirements Summaries
      3. 6.5.3. Data Specifications
      4. 6.5.4. Report Specifications
    6. 6.6. Summary
  12. 7. And Finally, the Beginning
    1. 7.1. Recommendations
    2. 7.2. A High-Level Diagram
    3. 7.3. Problem and Context Statement
    4. 7.4. Requirements Process
    5. 7.5. General Considerations
    6. 7.6. Scope
    7. 7.7. Other Potential Sections
    8. 7.8. A Complete Example
    9. 7.9. Summary
  13. 8. Reviewing, Reusing, and Maintenance
    1. 8.1. Review Cycles
    2. 8.2. Sign Off
    3. 8.3. What Happens Next
      1. 8.3.1. Application Proposals
      2. 8.3.2. Functional Specifications
      3. 8.3.3. Test Plans
    4. 8.4. Managing Requirements Through the Project Life Cycle
    5. 8.5. Maintaining Requirements After the Application Is in Production
    6. 8.6. Summary
  14. A. Software Requirements Document Template
    1. A.1. Executive Summary
      1. A.1.1. Problem and Context
      2. A.1.2. The Requirements Gathering Process
      3. A.1.3. General Considerations
      4. A.1.4. Scope
    2. A.2. Current State
      1. A.2.1. A Less Formal Structure
    3. A.3. Future State
    4. A.4. Gap Analysis
    5. A.5. Requirements Summaries
    6. A.6. Data Specifications
    7. A.7. Report Specifications
    8. A.8. Version History
3.17.154.139