Agile Documentation – A Pattern Guide to Producing Lightweight Documents for Software Projects

<p>Foreword ix</p>
<p>Preface xi</p>
<p>Acknowledgements xvii</p>
<p>Introduction 1</p>
<p>Project Background 11</p>
<p>1 Finding the Right Topics 19</p>
<p>Target Readers 24</p>
<p>Focused Information 26</p>
<p>Individual Documentation Requirements 28</p>
<p>Documentation Portfolio 30</p>
<p>Focus on Long–Term Relevance 34</p>
<p>Specification as a Joint Effort 36</p>
<p>Design Rationale 39</p>
<p>The Big Picture 40</p>
<p>Separation of Description and Evaluation 42</p>
<p>Realistic Examples 44</p>
<p>Experience Reports 46</p>
<p>2 Structuring Individual Documents 61</p>
<p>Structured Information 66</p>
<p>Judicious Diagrams 70</p>
<p>Unambiguous Tables 73</p>
<p>Guidelines for Readers 75</p>
<p>Thumbnail Sketches 77</p>
<p>Traceable References 78</p>
<p>Glossary 79</p>
<p>Document History 81</p>
<p>Experience Reports 82</p>
<p>3 Layout and Typography 93</p>
<p>Text on 50% of a Page 98</p>
<p>Two Alphabets per Line 100</p>
<p>120% Line Spacing 102</p>
<p>Two Typefaces 104</p>
<p>Careful Use of Type Variations 106</p>
<p>Careful Ruling and Shading 108</p>
<p>Adjacent Placement 109</p>
<p>Coherent Pages 111</p>
<p>Experience Reports 112</p>
<p>4 Infrastructure and Technical Organisation 117</p>
<p>Document Landscape 120</p>
<p>Document Archive 123</p>
<p>Wiki 125</p>
<p>Code–Comment Proximity 126</p>
<p>Reader–Friendly Media 128</p>
<p>Separation of Contents and Layout 131</p>
<p>Single Source and Multiple Targets 133</p>
<p>Import by Reference 136</p>
<p>Separation of Processing and Printing 138</p>
<p>Document Templates 139</p>
<p>Few Tools 142</p>
<p>Annotated Changes 144</p>
<p>Notification upon Update 145</p>
<p>Reorganisation upon Request 147</p>
<p>Experience Reports 149</p>
<p>5 Management and Quality Assurance 159</p>
<p>A Distinct Activity 161</p>
<p>One Responsible Author 164</p>
<p>Continuing Documentation 166</p>
<p>Writing and Reflection 168</p>
<p>Review Culture 170</p>
<p>Review Before Delivery 174</p>
<p>Customer Review 175</p>
<p>A Distant View 177</p>
<p>Information Marketplace 179</p>
<p>Knowledge Management 180</p>
<p>Experience Reports 182</p>
<p>Final Remarks 193</p>
<p>Pattern Thumbnails 197</p>
<p>Finding the Right Topics 197</p>
<p>Structuring Individual Documents 198</p>
<p>Layout and Typography 200</p>
<p>Infrastructure and Technical Organisation 201</p>
<p>Management and Quality Assurance 203</p>
<p>Glossary 205</p>
<p>References 211</p>
<p>Index 221</p>