Available:*
Library | Item Barcode | Call Number | Material Type | Item Category 1 | Status |
---|---|---|---|---|---|
Searching... | 30000010047030 | TS155.65 R87 2003 | Open Access Book | Book | Searching... |
On Order
Summary
Summary
Software documentation forms the basis for all communication relating to a software project. To be truly effective and usable, it should be based on what needs to be known. Agile Documentation provides sound advice on how to produce lean and lightweight software documentation. It will be welcomed by all project team members who want to cut out the fat from this time consuming task. Guidance given in pattern form, easily digested and cross-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 or online How to adapt the documentation process to the requirements of individual 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 customerBetter than offering pat answers or prescriptions, this book will help you to understand the elements and processes that can be found repeatedly in good project documentation and which can be shaped and designed to address your individual circumstance. The author uses real-world examples and utilises agile principles to provide an accessible, practical pattern-based guide which shows how to produce necessary and high quality documentation.
Author Notes
Andreas Ruping 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
Table of Contents
Foreword | p. ix |
Preface | p. xi |
Acknowledgements | p. xvii |
Introduction | p. 1 |
Project Background | p. 11 |
1 Finding the Right Topics | p. 19 |
Target Readers | p. 24 |
Focused Information | p. 26 |
Individual Documentation Requirements | p. 28 |
Documentation Portfolio | p. 30 |
Focus on Long-Term Relevance | p. 34 |
Specification as a Joint Effort | p. 36 |
Design Rationale | p. 39 |
The Big Picture | p. 40 |
Separation of Description and Evaluation | p. 42 |
Realistic Examples | p. 44 |
Experience Reports | p. 46 |
2 Structuring Individual Documents | p. 61 |
Structured Information | p. 66 |
Judicious Diagrams | p. 70 |
Unambiguous Tables | p. 73 |
Guidelines for Readers | p. 75 |
Thumbnail Sketches | p. 77 |
Traceable References | p. 78 |
Glossary | p. 79 |
Document History | p. 81 |
Experience Reports | p. 82 |
3 Layout and Typography | p. 93 |
Text on 50% of a Page | p. 98 |
Two Alphabets per Line | p. 100 |
120% Line Spacing | p. 102 |
Two Typefaces | p. 104 |
Careful Use of Type Variations | p. 106 |
Careful Ruling and Shading | p. 108 |
Adjacent Placement | p. 109 |
Coherent Pages | p. 111 |
Experience Reports | p. 112 |
4 Infrastructure and Technical Organisation | p. 117 |
Document Landscape | p. 120 |
Document Archive | p. 123 |
Wiki | p. 125 |
Code-Comment Proximity | p. 126 |
Reader-Friendly Media | p. 128 |
Separation of Contents and Layout | p. 131 |
Single Source and Multiple Targets | p. 133 |
Import by Reference | p. 136 |
Separation of Processing and Printing | p. 138 |
Document Templates | p. 139 |
Few Tools | p. 142 |
Annotated Changes | p. 144 |
Notification upon Update | p. 145 |
Reorganisation upon Request | p. 147 |
Experience Reports | p. 149 |
5 Management and Quality Assurance | p. 159 |
A Distinct Activity | p. 161 |
One Responsible Author | p. 164 |
Continuing Documentation | p. 166 |
Writing and Reflection | p. 168 |
Review Culture | p. 170 |
Review Before Delivery | p. 174 |
Customer Review | p. 175 |
A Distant View | p. 177 |
Information Marketplace | p. 179 |
Knowledge Management | p. 180 |
Experience Reports | p. 182 |
Final Remarks | p. 193 |
Pattern Thumbnails | p. 197 |
Finding the Right Topics | p. 197 |
Structuring Individual Documents | p. 198 |
Layout and Typography | p. 200 |
Infrastructure and Technical Organisation | p. 201 |
Management and Quality Assurance | p. 203 |
Glossary | p. 205 |
References | p. 211 |
Index | p. 221 |