SPA Conference session: Writing and Reviewing Technical Documents | |||
| One-line description: | Documents still form the lifeblood of software development in most organizations. This session aims to help you write better documents and provide more useful review feedback. | ||
| Session format: | Workshop (150 mins) [read about the different session types] | ||
| Abstract: | We all know that communication is a key part of successful software development. There has been so much recent focus on the direct, informal styles of communication that form part of agile development practices that you could be forgiven for thinking that the days of documentation in software development are numbered. However, in many organizations, documents still form the lifeblood of the software development process. There are requirements documents, technical specifications, blueprints, architectural descriptions, high-level design documents, low-level design documents, test specifications and documents with strange code names that form parts of the methodologies of major consultancies. If you move in the rarified atmosphere of the architect then you may find yourself writing as many documents to 'sell' your solution as you do to specify it. Even in the document-lite world of agile development, documents still exist in the form of wiki pages and story cards. Wherever you go you cannot escape the need to write things down in English before they hit the codeface. So, things are looking healthy for the humble document then? Well, possibly not. The problem is that many of them are rubbish. Their content is vague and their structure is inconsistent. In short, they are not fit for purpose. You encounter similar problems when reviewing documents written by other people. It is not usually socially acceptable just to write on it “this is tripe” and send it back. If you want to end up with a usable, useful document you need to provide purposeful feedback based on a critical assessment of where and how the document is lacking. In simple terms, this session aims to help you write better documents and provide more useful review feedback. It should help you to assess more critically the documents you create and the documents you read. It may change the way you think about documentation forever. | ||
| Audience background: | Architects, designers, developers, analysts and managers involved in any aspect of software development. | ||
| Benefits of participating: | * Create better structured documents. * Focus documents to their audience and purpose. * Provide better feedback on documents you review. * Ensure that your documents effectively get the right information across to your readers | ||
| Materials provided: | * Presentation slides. * Example documents for the reviewing and re-structuring exercises. | ||
| Process: | Presentation: Dissecting software development documents 1.Why documentation matters and scope of this session 2.Examining the dimensions of documents and how they are driven by context: 2.1Roles and forms of document – lifecycle, timeliness, etc. 2.2.Focus of a document – objective, audience and format 2.3.Structure of a document – disclosure sequence etc. 2.4.Document content – depth, persuasion, etc. Presentation: Reviewing documents 1.Examine variations on the following and how they would vary based on type of document, organization, etc: 1.1.Number of iterations you expect and the impact of this on review style 1.2.Critical analysis of structure and content 1.3.Styles for giving feedback Exercise: Reviewing a document 1.Work in groups 2.Provide groups with an example document (with vague or uneven content and inconsistent or inappropriate structure) 3.In groups, review it for audience, structure, depth, objectives, precision. 4.Provide answers to some fixed questions such as “who is the audience for this document?”, “give an example of the feedback you would provide” 5.Collate answers and comments as a whole session activity Presentation: Technical documents 1.Important aspects: audience, purpose, assumptions, structure, precision/accuracy 2.Types of technical document and lifecycle Exercise: Refactoring a technical document 1.Given the document from the previous exercise and the answers to the questions: Is the form right? What are the main parts to change? How would you restructure and what content is most in need of change? Is the content in the right sections? Give examples of how you would change it. 2.Each group in turn presents its document – describe proposed structure and content changes 3.Critique from other groups – does it now fit the audience and depth? Presentation: Selling your solution 1.Making an argument and critical thinking 2.Matching the document to the audience (e.g. don't be too technical, right terminology, right level) Exercise: Creating a selling document 1.Provide a bit more background on project from which the first document was taken 2.Groups create a basic selling document structure 3.Who is the audience and what points need to be raised where and in what order? 4.What arguments do you need to put forward and on what premises are they based? 5.Present each group in turn (could collate as a whole session if pressed for time) Summary and conclusions 1.What can you take back to your work? | ||
| Detailed timetable: | 00:00 – 00:25 Introductions, session objectives and Presentation: Document Principles 00:25 – 00:35 Presentation: Reviewing documents 00:35 – 01:05 Exercise: Reviewing a document 01:05 – 01:15 Presentation: Technical documents 01:15 – 01:45 Break 01:45 – 02:15 Exercise: Refactoring a technical document 02:15 – 02:25 Presentation: Selling your solution 02:25 – 02:55 Exercise: Creating a selling document 02:55 – 03:00 Summary and conclusions | ||
| Outputs: | * Collated answers and document structures from exercises. * Source materials provided to groups. The outputs will be presented as posters at the event, with summaries written up for the SPA2009 Outputs Wiki. | ||
| History: | None | ||
| Presenters | |||
| 1. Andy Longshaw Barclays Bank |
2. Nick Rozanski Barclays Global Investors |
3. | |