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
- About the Author
1. Telling Stories
- 1.1. What Must We Do?
- 1.2. Why Do We Learn Better From Stories?
- 1.3. How Do Story Elements Relate to Requirements?
- 1.4. What Are Software Requirements, and Who Are They For?
- 1.5. Why Projects Collapse (Without Detailed Requirements)
- 1.6. Why Have We Turned from the Path of Righteousness?
- 1.7. Can Stories Get Us Back on Track?
- 1.8. Making Structured Analysis into a Story
- 1.9. Who Should Do This Work?
- 1.10. Summary
2. The Language of Your Story
- 2.1. Clarity
- 2.2. Precision
- 2.3. Using a Consistent and Appropriate Level of Detail
- 2.4. Summary
3. Drawing Pictures
- 3.1. Why Data Flow Diagrams?
- 3.2. Data Flow Diagram Elements
- 3.3. Basic Rules
- 3.4. Summary and Detail Diagrams
- 3.5. About Creating Rough Diagrams
3.6. Guidelines for Design Clarity
- 3.6.1. Start at the Top and Flow Down and to the Left
- 3.6.2. Align Everything
- 3.6.3. Make Things the Same Size
- 3.6.4. Distribute Elements Consistently
- 3.6.5. Connect at Only Four Points
- 3.6.6. Use Only Straight Lines and 90-Degree Angles
- 3.6.7. Consider the Composition and Orientation
- 3.6.8. Use the Same Font and Sizes
- 3.6.9. Group Related Items and Annotate Diagrams to Add Meaning
- 3.7. Other Types of Diagrams
- 3.8. Summary
4. Explaining Processes and Finding Requirements
- 4.1. Naming Processes
- 4.2. Success Criteria
- 4.3. Started by
- 4.4. Results of
- 4.5. Elements of
- 4.6. Actions
- 4.7. Cross-References to Other Processes
- 4.8. Extracting Requirements
- 4.9. Options for Structuring Diagrams and Text
- 4.10. Adding Diagram and Section Introductions
- 4.11. Summary
5. Finding and Structuring the Content
- 5.1. You Are a Very Important Team Member
- 5.2. Building Rapport with the Project Team
5.3. Capturing the Critical Information
- 5.3.1. What Are the Business Purposes of the System?
- 5.3.2. What Are the Main Elements of the System?
- 5.3.3. What Does the System Do?
- 5.3.4. What Is the System Doing Well Now?
- 5.3.5. What Is the System Doing Poorly?
- 5.3.6. What Must the System Continue to Do?
- 5.3.7. What External Data Does the System Rely On?
- 5.3.8. What Data Must the System Provide to Other Systems?
- 5.3.9. What Do We Hope the New System Will Do Better
- 5.3.10. Other Lists
- 5.4. Writing the Outline
- 5.5. Summary
6. Creating the Body of the Document
- 6.1. Is Documenting the Current State Really Necessary?
- 6.2. Go Back to the Team
- 6.3. Writing the Future State
- 6.4. Checking for Completeness
- 6.5. Reference Material After the Story
- 6.6. Summary
- 7. And Finally, the Beginning
- 8. Reviewing, Reusing, and Maintenance
A. Software Requirements Document Template
- A.1. Executive Summary
- A.2. Current State
- A.3. Future State
- A.4. Gap Analysis
- A.5. Requirements Summaries
- A.6. Data Specifications
- A.7. Report Specifications
- A.8. Version History
- Title: Telling Stories: A Short Path to Writing Better Software Requirements
- Release date: March 2009
- Publisher(s): Wiley
- ISBN: 9780470437001