Cover image for Agile documentation : a pattern guide to producing lightweight documents for software projects
Title:
Agile documentation : a pattern guide to producing lightweight documents for software projects
Personal Author:
Publication Information:
Chichester, West Sussex : John Wiley & Sons, 2003
ISBN:
9780470856178

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 customer

Better 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

Forewordp. ix
Prefacep. xi
Acknowledgementsp. xvii
Introductionp. 1
Project Backgroundp. 11
1 Finding the Right Topicsp. 19
Target Readersp. 24
Focused Informationp. 26
Individual Documentation Requirementsp. 28
Documentation Portfoliop. 30
Focus on Long-Term Relevancep. 34
Specification as a Joint Effortp. 36
Design Rationalep. 39
The Big Picturep. 40
Separation of Description and Evaluationp. 42
Realistic Examplesp. 44
Experience Reportsp. 46
2 Structuring Individual Documentsp. 61
Structured Informationp. 66
Judicious Diagramsp. 70
Unambiguous Tablesp. 73
Guidelines for Readersp. 75
Thumbnail Sketchesp. 77
Traceable Referencesp. 78
Glossaryp. 79
Document Historyp. 81
Experience Reportsp. 82
3 Layout and Typographyp. 93
Text on 50% of a Pagep. 98
Two Alphabets per Linep. 100
120% Line Spacingp. 102
Two Typefacesp. 104
Careful Use of Type Variationsp. 106
Careful Ruling and Shadingp. 108
Adjacent Placementp. 109
Coherent Pagesp. 111
Experience Reportsp. 112
4 Infrastructure and Technical Organisationp. 117
Document Landscapep. 120
Document Archivep. 123
Wikip. 125
Code-Comment Proximityp. 126
Reader-Friendly Mediap. 128
Separation of Contents and Layoutp. 131
Single Source and Multiple Targetsp. 133
Import by Referencep. 136
Separation of Processing and Printingp. 138
Document Templatesp. 139
Few Toolsp. 142
Annotated Changesp. 144
Notification upon Updatep. 145
Reorganisation upon Requestp. 147
Experience Reportsp. 149
5 Management and Quality Assurancep. 159
A Distinct Activityp. 161
One Responsible Authorp. 164
Continuing Documentationp. 166
Writing and Reflectionp. 168
Review Culturep. 170
Review Before Deliveryp. 174
Customer Reviewp. 175
A Distant Viewp. 177
Information Marketplacep. 179
Knowledge Managementp. 180
Experience Reportsp. 182
Final Remarksp. 193
Pattern Thumbnailsp. 197
Finding the Right Topicsp. 197
Structuring Individual Documentsp. 198
Layout and Typographyp. 200
Infrastructure and Technical Organisationp. 201
Management and Quality Assurancep. 203
Glossaryp. 205
Referencesp. 211
Indexp. 221