Agile Documentation
A Pattern Guide to Producing Lightweight Documents for Software Projects
Published on 1. December 2004
244 pages
978-0-470-85624-6 (ISBN)
Description
Software documentation forms the basis for all communicationrelating to a software project. To be truly effective and usable,it should be based on what needs to be known. AgileDocumentation provides sound advice on how to produce lean andlightweight software documentation. It will be welcomed by allproject team members who want to cut out the fat from this timeconsuming task. Guidance given in pattern form, easily digested andcross-referenced, provides solutions to common problems.
Straightforward advice will help you to judge:
* What details should be left in and what left out
* When communication face-to-face would be better than paper oronline
* How to adapt the documentation process to the requirements ofindividual projects and build in change
* How to organise documents and make them easily accessible
* When to use diagrams rather than text
* How to choose the right tools and techniques
* How documentation impacts the customer
Better than offering pat answers or prescriptions, this bookwill help you to understand the elements and processes that can befound repeatedly in good project documentation and which can beshaped and designed to address your individual circumstance. Theauthor uses real-world examples and utilises agile principles toprovide an accessible, practical pattern-based guide which showshow to produce necessary and high quality documentation.
Straightforward advice will help you to judge:
* What details should be left in and what left out
* When communication face-to-face would be better than paper oronline
* How to adapt the documentation process to the requirements ofindividual projects and build in change
* How to organise documents and make them easily accessible
* When to use diagrams rather than text
* How to choose the right tools and techniques
* How documentation impacts the customer
Better than offering pat answers or prescriptions, this bookwill help you to understand the elements and processes that can befound repeatedly in good project documentation and which can beshaped and designed to address your individual circumstance. Theauthor uses real-world examples and utilises agile principles toprovide an accessible, practical pattern-based guide which showshow to produce necessary and high quality documentation.
More details
Other editions
Additional editions
Andreas Rüping
Agile Documentation
A Pattern Guide to Producing Lightweight Documents for Software Projects
Book
06/2003
Wiley
€47.00
Shipment within 10-20 days
Person
Andreas Rüping is a member of the patterns think-tank, Hillside Europe, and has acted as the chairman of several EuroPLoP Conferences. He has 12 years industry experience of software development, most recently as a software engineer and consultant at sd&m software design & management AG in Germany.
Content
Foreword ix
Preface xi
Acknowledgements xvii
Introduction 1
Project Background 11
1 Finding the Right Topics 19
Target Readers 24
Focused Information 26
Individual Documentation Requirements 28
Documentation Portfolio 30
Focus on Long-Term Relevance 34
Specification as a Joint Effort 36
Design Rationale 39
The Big Picture 40
Separation of Description and Evaluation 42
Realistic Examples 44
Experience Reports 46
2 Structuring Individual Documents 61
Structured Information 66
Judicious Diagrams 70
Unambiguous Tables 73
Guidelines for Readers 75
Thumbnail Sketches 77
Traceable References 78
Glossary 79
Document History 81
Experience Reports 82
3 Layout and Typography 93
Text on 50% of a Page 98
Two Alphabets per Line 100
120% Line Spacing 102
Two Typefaces 104
Careful Use of Type Variations 106
Careful Ruling and Shading 108
Adjacent Placement 109
Coherent Pages 111
Experience Reports 112
4 Infrastructure and Technical Organisation 117
Document Landscape 120
Document Archive 123
Wiki 125
Code-Comment Proximity 126
Reader-Friendly Media 128
Separation of Contents and Layout 131
Single Source and Multiple Targets 133
Import by Reference 136
Separation of Processing and Printing 138
Document Templates 139
Few Tools 142
Annotated Changes 144
Notification upon Update 145
Reorganisation upon Request 147
Experience Reports 149
5 Management and Quality Assurance 159
A Distinct Activity 161
One Responsible Author 164
Continuing Documentation 166
Writing and Reflection 168
Review Culture 170
Review Before Delivery 174
Customer Review 175
A Distant View 177
Information Marketplace 179
Knowledge Management 180
Experience Reports 182
Final Remarks 193
Pattern Thumbnails 197
Finding the Right Topics 197
Structuring Individual Documents 198
Layout and Typography 200
Infrastructure and Technical Organisation 201
Management and Quality Assurance 203
Glossary 205
References 211
Index 221
Preface xi
Acknowledgements xvii
Introduction 1
Project Background 11
1 Finding the Right Topics 19
Target Readers 24
Focused Information 26
Individual Documentation Requirements 28
Documentation Portfolio 30
Focus on Long-Term Relevance 34
Specification as a Joint Effort 36
Design Rationale 39
The Big Picture 40
Separation of Description and Evaluation 42
Realistic Examples 44
Experience Reports 46
2 Structuring Individual Documents 61
Structured Information 66
Judicious Diagrams 70
Unambiguous Tables 73
Guidelines for Readers 75
Thumbnail Sketches 77
Traceable References 78
Glossary 79
Document History 81
Experience Reports 82
3 Layout and Typography 93
Text on 50% of a Page 98
Two Alphabets per Line 100
120% Line Spacing 102
Two Typefaces 104
Careful Use of Type Variations 106
Careful Ruling and Shading 108
Adjacent Placement 109
Coherent Pages 111
Experience Reports 112
4 Infrastructure and Technical Organisation 117
Document Landscape 120
Document Archive 123
Wiki 125
Code-Comment Proximity 126
Reader-Friendly Media 128
Separation of Contents and Layout 131
Single Source and Multiple Targets 133
Import by Reference 136
Separation of Processing and Printing 138
Document Templates 139
Few Tools 142
Annotated Changes 144
Notification upon Update 145
Reorganisation upon Request 147
Experience Reports 149
5 Management and Quality Assurance 159
A Distinct Activity 161
One Responsible Author 164
Continuing Documentation 166
Writing and Reflection 168
Review Culture 170
Review Before Delivery 174
Customer Review 175
A Distant View 177
Information Marketplace 179
Knowledge Management 180
Experience Reports 182
Final Remarks 193
Pattern Thumbnails 197
Finding the Right Topics 197
Structuring Individual Documents 198
Layout and Typography 200
Infrastructure and Technical Organisation 201
Management and Quality Assurance 203
Glossary 205
References 211
Index 221
