The book walks you through the production of a sophisticated air hockey game. The book covers the basics of Xcode, animation, movement, touch, using sound, physics, and artificial intelligence. In addition the book shows you how to create all the images you need for your game, including icons and iTunes graphics. There is also a chapter on finding and creating sound effects for the game. The final chapter walks through submitting apps to the App Store, including the submission process, how to deal with rejections, and marketing your game once you have created it.

Todd has an excellent writing style, making the book easy to read and follow. In addition to providing the code, Todd gives interesting and informative explanation on why he made certain decisions when creating the game. Todd also gives extensive guidance on best practices, and tips on tools and resources to use when building your apps. One of my favourite aspects of the book is that as you build the game in stages, you get to see the potential problems and how to fix them as you go along. You are not seeing the finished code from the outset, but actually see the code evolving as you go through the book. This helps to promote understanding of the code you are writing, but also how to think through problems you may come across when you write your own games.

I have found games programming books quite intimidating in the past, but I’ve learnt a great deal from reading this book and it has given me the confidence to have a go at writing my own game.

I highly recommend this book for anyone interesting in learning developing for iPhone and iPad.

Find out more from the O’Reilly Product page.

The following article was produced for and published in the ISTC Communicator, Winter 2011.

The ASTC (NSW) Technical Communication Conference was held in Sydney on the 28^th and 29^th of October with around 60 attendees.

The theme of the conference ’More than words’ was chosen to reflect the fact that although words are important, there are many other skills and tasks required for effective technical communication. The sessions across the two days reflected this theme, with everything from agile development to illustrations, and webinars to wikis.

Conference keynote

The keynote presentation on Friday morning was by Professor Pam Peters, Adjunct Professor of Linguistics at Macquarie University. This session covered practice and research in a number of areas where formatting can be used in print and online materials to improve the readability and accessibility of technical and scientific writing. Areas included text formatting such as utilising different typography and styles to highlight information; how fully justified text inhibits a user’s ability to read the text, and the importance of reducing the complexity of sentences.

Other ways of communicating information were also presented such as the use of photos to tell a story, and graphs and illustrations to convey meaning across space and time. There were interesting examples of different attempts to provide context for terms and definitions, such as tree representations, concept maps, ontologies, and horizontal relationship diagrams. The idea is to provide ways of making new terms accessible to users with no knowledge of a particular field, or for whom English is a second language.

Working practices and standards

A number of the sessions focused on techniques for working in projects or with clients. In ’Keeping your customer happy’ Elizabeth Abbott provided a number of hints and tips for working with customers. Most importantly, don’t argue with the customer even if you know better!

Julie McKibbin gave a presentation on project management including a practical group exercise to plan the preparation of a roast dinner. What was surprising was the variety of different ways a roast dinner could be planned, and how many teams resorted to McDonald’s as a backup plan!

There was a strong focus on standards with the presence of Working Group 2 who scheduled their meeting alongside the conference. In addition to a Q&A panel with four of us from WG2, Annette Reilly provided some best practice from the ISO/IEC/IEE 26512: 2011 Requirements for acquirers and suppliers of user documentation International Standard in her presentation on ’Winning proposals for documentation’.

I had the first presentation to give on the Saturday morning ’Agile development – a guide for writers’ which included best practices from ISO/IEC 26515 Developing user documentation in an agile environment, in addition to my own experiences with agile, both good and bad.

A bit of everything

David Whitbread presented ’A bit of everything – multiple platforms with minimal editing’. The presentation covered a range of techniques for creating content for presentation in different formats. In his work he needs to extract information from very busy solicitors. The answer to this was to get the solicitors to quickly record the information in the form of a podcast. This podcast material could then be reused to create a transcript and other written content. Another example demonstrated was the use of interactive PDFs for presenting offline but navigable content.

James Robertson gave an inspiring presentation on ’Delivering surprise and joy to staff’ with examples of where serious companies have added joy into their employees lives through well designed, smart, collaborative, and even fun intranets.

Wikis and webinars

Steve Moss described his experiences of using both face-to-face workshops and webinars to deliver education, including the pros and cons of each approach. Steve also discussed the issues around running a webinar, such as choosing webinar software and the planning steps required to run a successful webinar. It was clear from the presentation that webinars are an excellent way to deliver education and have a number of benefits such as significantly reduced costs and the potential for global participation. It is important to have a plan B in case the technology goes wrong though!

A presentation each was given by on using Confluence by Sarah Maddox and Paul Watson including workflows for using a wiki, collaboration, and creating PDF content.

Illustrations and wordless instructions

Charles Cave presented best practices on designing illustrations to use in technical information, including styles, the use of callouts, ordering, and flow charts. He also advocated the use of video for explaining steps. Many of the issues raised by Charles were also highlighted in Richard Hodgkinson’s presentation on Wordless Instructions. Richard’s presentation covered the story of how wordless instructions were designed, developed, and tested for one of IBM’s typewriter products. The story also highlighted the pitfalls of inadequate instructions leading to damage to both the product and the users!

Death by PowerPoint

The final session by Frank ‘Choco’ Munday was guaranteed to wake anyone who had been sleeping in the conference. Choco didn’t advocate the need to throw PowerPoint away like some, but instead provided tips (well commands actually) on what not to do in a PowerPoint presentation!

When I was 19 I kick started a collection of my own when two big sets were reduced, a castle set (I’ve always loved the castle sets) and an underwater base. After giving myself permission to buy it, I bought all sorts of sets that I like, western, more castle, native, and obviously Lego System. I even saw the bad old days of sets where there were solid walls instead of bricks to build them. I have a fire station that was so disappointing because there was hardly any construction to be done!

Thankfully those days are long gone. There are many many brilliant sets, and I now have quite a lot of Lego! In addition to the wonderful worlds of Lego sets for children (which I have and I love), there are many brilliant models for those of us young at heart and with an inner child thats trying to get out. What I mean to say is of course sets that are designed for a more mature audience. Sets for grown ups! In particular are the modular building sets complete with advanced building techniques and nice little details on the outside and the inside.

They may be a bit more grown up, but they are certainly still for enjoying. Not like those fun-less folks that buy toys just to ‘collect them’, and then shove them in the attic, never opened. Pfff, that is wasteful and boring! I enjoy the whole experience of building and I enjoy the experience of them being built. In fact because they have the added complexity I like them even more. And they are very cool when you have a whole street of them:

From the left: Cafe/Hotel, Greengrocers, Fire Station, Townhouse/Pet Shop, Grand Emporium

Each floor of each building is a separate module, so you can take them apart to look inside. Did you spot the banker?

I can’t wait for the next sets to add to my street!

The first chapter in the review version discusses strategies for introducing users to the contents of an electronic book. The chapter discusses how the traditional ‘table of contents’ is a poor substitute compared to flicking through a book to get to grips with the contents. The chapter gives a variety of ideas on more exciting ways of enticing users with the contents of the book. The following chapter deals with the benefits of providing a good index and a variety of methods for searching for specific content within books. The final chapter in the review version of the book extends the discussion from chapter one on navigation within books, including how the user knows where they are, how much is left to go, and how to get back to where they have been.

Pete has a chatty and informal style, and his writing demonstrates his enthusiasm for producing compelling books and educational material for mobile. The book contains some interesting ideas around user interface design for accessing and locating information within books and mobile applications. I found it particularly valuable when the ideas were illustrated with the use of real-world examples that I could actually go and take a look at, for example I was introduced to some interesting mobile apps that I had not seen before. Not all of the ideas are illustrated with examples, even where a real-world example is discussed. The book itself talks about a picture being worth a thousand words and for those ideas without a picture to explain them yet I’d like to see those added (chapter one seems incomplete in this regard).

A problem I did have with this version is the blurry line between eBook, book reader, mobile app, and web interface. The book gives ideas about how the experience of using an eBook can be improved through changes to interface design, but sometimes it is unclear whether this can be done in eBook format, whether you need to make a mobile app to do it, or whether the change needs to be made at the level of the eBook reader. I’m left wanting to know more, not programmatically how to create some of these features, but whether I can do them in eBook format or I have to write an app. I’m left not being sure who the book is written for, is it for authors of books, application developers, publishers, or eBook reader developers? The book seems part design advice and part wishlist! Also, the book is ‘just’ a normal book, I had hoped it might demonstrate some of the whizzy ideas suggested!

Saying all that, there are some good ideas and sound principles in the book that will be of interest to folks involved in authoring, publishing, and developing applications for mobile devices.

Find out more from the product page at O’Reilly Media

Phil showed me around the diffuser and some of the aero on the car, and then I got curiously excited to see the plank. So I had to get a picture of the underside of the car. Which looks more dodgy than it really is, it was actually the plank I wanted to see!

Well I was excited..

Anyway, Saturday was the big day when we’d get to see the cars driving down the centre of Milton Keynes. We managed to secure a spot that at least meant no-one could get in the way of us on some steps. It was a long cold wait for the action. To sum up in slightly fewer seconds than we have of video footage, Mark drove his F1 which was cool. A dude rode a motorcycle out of view. David Coulthard drove a loud Nascar car, which was cool. Seb drove his F1 car which was cool. The motorcycle dude drove it even more out of view. Then Seb and Mark drove their F1 cars at each other, without crashing, which was super cool! But you need to see the shaky footage from my viewpoint:

Hubby also got me a souvenir/early Christmas present. These are perfect for our F1 simulator!

For more photos of the day (and the shoes) take a look here.

ISO/IEC 26511:2011 Systems and software engineering — Requirements for managers of user documentation

ISO/IEC 26511:2011 specifies procedures for managing user documentation throughout the software life cycle. It applies to people or organizations producing suites of documentation, to those undertaking a single documentation project, and to documentation produced internally, as well as to documentation contracted to outside service organizations. It provides an overview of the software documentation and information management processes, and also presents aspects of portfolio planning and content management that user documentation managers apply. It covers management activities in starting a project, including setting up procedures and specifications, establishing infrastructure, and building a team. It includes examples of roles needed on a user documentation team. It addresses measurements and estimates needed for management control, and the use of supporting processes such as change management, schedule and cost control, resource management, and quality management and process improvement. It includes requirements for key documents produced for user documentation management, including documentation plans and documentation management plans. ISO/IEC 26511:2011 is independent of the software tools that may be used to produce or manage documentation, and applies to both printed documentation and on-screen documentation. Much of its guidance is applicable to user documentation for systems including hardware as well as software.

ISO/IEC 26512:2011 Systems and software engineering — Requirements for acquirers and suppliers of user documentation

ISO/IEC/IEEE 26512:2011 was developed to assist users of ISO/IEC 15288:2008 or ISO/IEC 12207:2008 to acquire or supply software user documentation as part of the software life cycle processes. It defines the documentation process from the acquirer’s standpoint and the supplier’s standpoint. ISO/IEC/IEEE 26512:2011 covers the requirements for information items used in the acquisition of user documentation products: the Acquisition Plan, Document Specification, Statement of Work, Request for Proposals, and the proposal. It provides an overview of the software user documentation and information management processes which may require acquisition and supply of software user documentation products and services. It addresses the preparation of requirements for software user documentation. These requirements are central to the user documentation specification and Statement of Work. It includes requirements for primary document outputs of the acquisition and supply process: the Request for Proposal and the Proposal for user documentation products and services. It also discusses the use of a Documentation Management Plan and a Document Plan as they arise in the acquisition and supply processes. ISO/IEC/IEEE 26512:2011 is independent of the software tools that may be used to produce documentation, and applies to both printed documentation and on-screen documentation. Much of its guidance is applicable to user documentation for systems including hardware as well as software.

ISO/IEC 26513:2009 Systems and software engineering – Requirements for testers and reviewers of user documentation

SO/IEC 26513:2009 was developed to assist those who test and review software user documentation as part of the software life cycle process. It will be useful for testers, reviewers and other related roles, including a variety of specialists such as information designers or architects involved in planning the structure and format of products in a documentation set, as well as usability specialists and business analysts who identify the tasks the intended users will perform with the software.

Documentation evaluations are performed throughout the document’s development, production and maintenance and through a range of methods such as:

• Documentation review
• System testing
• Usability testing
• Accessibility testing
• Localization and customization testing.

The standard also contains two annexes including informative checklists useful at each phase of the verifying process of the documentation quality that allow testers and reviewers to highlight any defects or non-conformances.

ISO/IEC 26514:2008 Systems and software engineering — Requirements for designers and developers of user documentation

ISO/IEC 26514:2008 provides requirements for the design and development of software user documentation as part of the life cycle processes. It defines the documentation process from the viewpoint of the documentation developer. ISO/IEC 26514:2008 also covers the documentation product. It specifies the structure, content, and format for user documentation, and also provides informative guidance for user documentation style. It is independent of the software tools that may be used to produce documentation, and applies to both printed documentation and on-screen documentation. Much of ISO/IEC 26514:2008 is also applicable to user documentation for systems including hardware.

ISO/IEC 26515:2011 Systems and software engineering — Developing user documentation in an agile environment

ISO/IEC 26515:2011 specifies the way in which user documentation can be developed in agile development projects. It is intended for use in all organizations that are using agile development, or are considering implementing their projects using these techniques. It applies to people or organizations producing suites of documentation, to those undertaking a single documentation project, and to documentation produced internally, as well as to documentation contracted to outside service organizations. ISO/IEC 26515:2011 addresses the relationship between the user documentation process and the life cycle documentation process in agile development. It describes how the information developer or project manager may plan and manage the user documentation development in an agile environment. It is intended neither to encourage nor to discourage the use of any particular agile development tools or methods.

ISO/IEC 15289:2011 Systems and software engineering — Content of life-cycle information products (documentation)

And some more photos of Sydney here.

This week I gave a presentation with this title to the Technical Communication UK 2011 Conference. I’ve attached the slides that I used in the conference here: TCUK11_Agile, although they won’t really mean much to anyone! The majority of the presentations I’ve done in the past do rely on Power Point (spit spit) and an excess of text. Given that neither standards or agile are an exciting subject, there was a very large chance the presentation would be all text and very dull! So I wanted to use lots of pictures, but still make sure that I could remember what I wanted to say. So.. because they won’t make any sense on their own, here is a write-up of what I said (or at least intended to say)!

First I’ll start with a little of my background and why I was doing a presentation on this subject. I wear a number of different hats, and for this presentation I was wearing my ‘documentation standards’ hat. I have the privilege of being the UK Principal Expert for the BSI for standards on documentation in software and systems, and part of an ISO working group (ISO/IEC JTC1/SC7/WG2). In this role I’m editor for international standards, previously one on testing and reviewing user documentation, and the one that I will talk about in this presentation on developing user documentation in an agile environment. (The work we do on the standards is all voluntary btw).  No-one sensible calls themselves an expert in agile development, but I have been working with more or less successful teams using agile development within IBM for about 3 years.

The presentation itself covers a little bit about standards and what we do in the working group, a brief introduction to agile development, what agile development means to writers, and then finally some of the guidance and requirements from the standard.

Firstly, I’ll explain this acronym:  ISO/IEC JTC1/SC7/WG2. This acronym explains where our working group fits into the food chain of International Standards development.

Breaking the acronym down, ISO/IEC JTC1 is broken down into the following parts. ISO is the International Standards Organisation and IEC is the International Electrotechnical Commission. The  JTC1 means Joint Technical Committee. So this part means that we’re part of a joint technical committee of the ISO and IEC. This committee is responsible for producing International Standards for Information Technology. SC7 is one of several sub-committees, and sub-comittee 7 is responsible for developing standards for software and systems engineering. Finally WG 2 is one of a number of working groups underneath the sub-comittee. Working group 2 is responsible for producing standards for documentation in software and systems engineering.

So what is a standard? A standard is a set of mandatory requirements established by consensus and maintained by a recognized body to prescribe a disciplined uniform approach or specify a product, that is, mandatory conventions and practices. This is a good thing for the production of products because they work together in a safe way (see the photo on slide 6 of what happens when there is no standard!) and is good for business. If an organisation complies with a standard then you can be sure they are following best practices, and potentially work more effectively with them. The ISO standards are developed by negotiation and consensus with experts around the world, meaning that they are appropriate for universal and worldwide use. The standards are developing iteratively, with drafts created by the working groups by consensus, and then sent out for ballot and review by national standards organisations, presenting the standards to a larger body of experts and organisational representatives.

Working group 2 develops standards relating to both documentation in the life-cycle and user documentation for software and systems. For user documentation we have a suite of standards that are aimed at different user roles involved with developing user documentation including authors, designers, managers, reviewers, testers, acquirers, and suppliers. The standard on developing user documentation in an agile environment is part of this suite of standards, but is designed to supplement the existing standards by providing activities and behaviours that are applicable specifically to an agile environment.

So why did we decide to do a standard on agile? Well, firstly as suggested above, agile development can certainly be quite a different way of working for teams used to more traditional methods. Agile is being increasingly adopted by organisations, but the existing guidance on agile is very developer focussed. There isn’t very much out there for writers and user documentation developers. We felt the community would benefit from the guidance the standard could provide, but also by adhering to the requirements in the standard would promote best practices and help writing teams make agile effective in their own organisations.

As writers we may not be able to change the way the developers work, but we can influence and improve the way we work with them!

So what is agile all about? You may have heard lots of different terminology to describe agile, and their are different methodologies with their own terminology and activities. There are however some common terms and practices that this presentation, and the standard, focus upon. The truth is also that organisations doing agile all seem to be doing something different! Contrary to myth (and the cartoon on slide 9) agile is not all about abandoning planning, chucking away all the documentation, and throwing together some rubbish code. This approach is known as cowboy programming!

The major aim of agile is to produce and ship useful, working software as early as possible to customers, whilst avoiding some problems of more traditional software methods. <aside>I can’t (with this particular hat on) make statements about whether agile is better or not than other methods. Have a look on the web for the background and comparisons, especially http://agilemanifesto.org/). Check back in November when I’ll be wearing a different hat </aside> Agile methods have two main areas of impact, how the software is developed and delivered, and how the teams work.

Software is delivered early, frequently, and continuously. What this means is that as soon as a feature, that is useful to the user, has been developed and tested, it is delivered to the customers. Then the next function is delivered and shipped, and so on continuously. The idea is that this method of development and delivery is sustainable. Working software is the measure of progress in agile. When something works and is useful, it is ready to be shipped. But if it does not work, the team cannot move on until it is fixed. These cycles of development and delivery are known as sprints or iterations. Agile development also embraces changing requirements. Because of the frequent release of software and the involvement of stakeholders in agile, more feedback is received and excepted from customers, so more might changes come in. Agile doesn’t plan for the long term, although there may be a high level plan for the long term providing a strategic direction, these plans are not highly detailed, and detailed planning happens only for the current iteration, and perhaps the next. This means that it is very easy to change plans as development goes on. If something is urgent then everything can stop and the iteration be re-planned, or more commonly the plan for the next iteration is altered.

As mentioned, a big change that agile development often makes is the way that teams work together. Firstly is the delegation of responsibility. Agile teams are known as self-directing teams. Management may assign resource and tasks to agile teams, but the team members themselves are responsible for working out how to work together and how to solve their technical problems. Within agile customer collaboration and stakeholder contribution is recognised as being very important, and this means that everyone with an interest in the development, including users and their representatives should have regularly contact with the development team. Ideally on a daily basis. Agile asserts that face to face communication is more effective than reliance on detailed or formal life-cycle documentation. Its better to get on with the design and development and to produce working software, than spend your time writing about how you are going to do it. Agile often makes the assumption that the team members and everyone involved are in the same place and can talk face to face. This is unrealistic for many organisations, but there are other communication methods that can be effective even where workers are remote or even in different time zones. The final behaviour of an agile team is to actively seek to improve their own effectiveness and performance, and this is done through regular lessons learned activities.

So what does agile mean for writers?

Development takes place in repeated cycles called iterations or sprints. These cycles contain design, development, testing and documentation. They typically last between 2 weeks and 2 months. These sprints can have a significant impact on what gets written and when. Because what needs to be produced is user documentation that helps the user to use the feature that is developed, task information tends to be the priority in the iteration. This mean that concept guides and reference information, for example, have to come later in the iteration or possibly even a different iteration. The documentation might also need to be written before the code is developed. The documentation has to be written with time provided for testing, feedback and fixing problems before the end of the iteration.

Design still happens in agile (really!), but communication of the intent and behaviour of the user documentation may instead be provided by face to face communication, rather than through the use of detailed, formal documentation plans.  For many writers agile provides an opportunity to get involved with the design process, and even providing more visibility for the design and requirements of the user documentation. Design takes place in each iteration and should involve stakeholders representing the user.  The user documentation can itself become the central point for communicating the external design of the software, providing a source of how the software looks to the users and how they will interact with it.

There is less reliance on detailed design specifications and technical documentation for communication, and more reliance on other types of design documentation depending on the size of teams and the locations of team members. Content storage systems that enable content to be captured quickly and cheaply and are rapid to update may be effectively used to store these less formal design documents, for example wikis. Because coding usually happens quicker in agile, prototypes are often available early to demonstrate how the software looks and how the user will interact with it.

A principle of agile is “maximising work not done”.  This means deciding what the user really needs and producing this as the priority. If a user doesn’t want or need a function, don’t bother developing it. This actually means that the software is leaner and more usable to the customer. The developer shouldn’t implement a function because it is ‘cool’ but because the user needs it! This principle applies to user documentation in the same way as it does to code. If the user doesn’t need it, don’t write it!  This will often mean not duplicating content in different forms. For example, if a tutorial will be more useful and cover what is needed for the user of the new function then this will be produced alone rather than producing both this an extensive library of documentation covering the same topic. Or using embedded assistance rather than documenting the interface. You don’t have time to write everything, and write everything in multiple ways, so prioritise based on user needs!

Agile has a stronger focus on working with the users or stakeholders representing the users, and also the early and regular release of software provides writers with opportunities to get feedback on the documentation from both users and stakeholders on the project.

A major principle of agile is to accept and embrace changing requirements that come as a result of changing needs for users or feedback on software delivered to users. This means that the plans may change and work that has previously been developed may be changed or even completely removed from the products. This applies to program code and the documentation developed along side it. It can be difficult for members of the development team to discard work they may have spent a lot of time developing, but the end result a leaner and more useful product for the users. This does mean that more time may be spent on reworking the documentation than writers are used to.

Most agile projects use self-directing teams and promote development sprints, teamwork, collaboration, and process adaptability throughout the life cycle of the project.  In agile, teams are given responsibility for delivering the functionality assigned to them in the iterations. Rather than being given detailed design specifications to work from, the team comes up with their own designs and decide themselves how to solve the technical problems. Teams are multidisciplinary, which means that the teams contain developers, testers, writers, and others for example service and usability personnel. Staff may also be expected to change role as needed by the team, for example a writer may be asked to do testing, or another member of the team may be asked to help with writing depending on the requirements of the team at a particular point in the iteration.

Before moving on to give some guidance and requirements from the standard, just a quick word about how standards are used. The ISO International Standards primarily provide requirements – an organisation or project can claim conformance with a standard – meaning that they follow the best practices as laid out in the standard.  This conformance can be important in contracts between different organisations. Standards are also an excellent resource for organisations or products that don’t need to claim conformance because they contain best practices established from the experiences of diverse organisations across the world.  If an organisation wants to claim conformance, then the use of shall, should, and may in the standard indicates what you must follow and to what extent within the standard. Shall means an activity or behaviour you must adhere to exactly as specified in order to claim compliance.  Should is a recommended practice and where possible adhered to, but it might not be possible for all projects. And May is an action that is permissible within the limits of the standard, and usually is providing guidance on a way that a particular activity or behaviour could be done.

The first major section of the standard provides requirements and guidance on the management of information development in an agile environment and is aimed at managers of user documentation. The manager depends on the organisation or project and may be a team-leader, the project manager or a manager of technical communicators.

The documentation manager has an important move in agile development, not least because they need to agree the move to agile in the first place and ensure that the writing team are provided with adequate education.  They must also work with the other designers and project managers to understand roles and responsibilities whilst using agile development. Some projects may choose to not do agile for the documentation, or only part of the documentation (for example only online help and not printed help). <aside>Removing my hat just slightly, based on comments from the conference a big problem for some organisations is the writing team not being part of agile. For it to work effectively the writers need to be part of the agile team – this is good for everyone. The manager ought to make sure that the writing team are fully involved in the agile process if it is adopted. Ways to get involved are included here and especially in the standard. In  agile the writers need to stand up to development and say “We are valuable, doc is important to customers. We *must* be part of the team”. Be brave! You are valuable and have a valuable contribution to make!</aside>

Anyway, what was I saying? Ah yes, user documentation management. Most of the management of user documentation is much as it would be for any project with resourcing, costings, planning, prioritising, ensuring effective communication between development and the writing team, and so on, but an important part of the management role in agile is taking a look at the big picture. One of the downsides of agile is that it becomes very feature focussed and work items that don’t relate directly to code being written in the iteration tend to get overlooked or problematic to include. Planning in the iteration has to include these other work items, this may include items such as install, migration, and troubleshooting documentation, concepts, and reference information. These must be planned and included in the schedules, and can be completed in quieter iterations, or perhaps as work given to a team working outside of the iterative process. Other tasks that might need to be planned for are quality work (such as information architecture, migration to new tools, maintenance of previous releases, and so on).

Another important principle in agile is regular reflection by teams on how to make themselves more effective, and then adjusting their behaviour accordingly. At the end of each sprint teams should discuss the successes and failures of the previous sprint. The information development lead or project manager should encourage the members of the documentation team to report any difficulties promptly, and seek assistance in solving them if required, either through the status meetings or directly to the manager.

Planning for the project requires planning the content for individual sprints. Documentation produced in each iteration is likely to be task orientated information to help the user use the function that has been developed in that sprint, although it may also be possible to schedule feature-related concept and reference materials within the individual sprints.

<aside>I’ve taken my hat off again.. Ignoring sizing is probably the most important factor in getting agile wrong! Because iterations tend to be a set size for a project, there is a temptation to keep the iterations the same size and squeeze function of all sizes into this iteration length, regardless of how long it actually is! The desire to ‘embrace changing requirements’ can also mean that management want to add something new part way through an iteration, by squeezing it in! Be very wary of anyone who gives you ‘extended requirements’. Truly you can add stuff into an iteration if you make progress that is better than expected – but please, the only way you can add anything new in an already complete plan is to take something else out! Fight it, make them prioritise! Again, be brave!</aside>

Erm, what was I saying? Ah yes, sizing. The sizing also needs to include time for reviews, testing and fixing problems. A size should be provided by the technical writer for each task that they are responsible for in the sprint.  Depending on the sprint the technical writer should break down large tasks into smaller tasks. Tasks that are sized above 3 to 5 days may be difficult to adequately estimate in a sprint, and may result in slippage if the task cannot be completed in the sprint. For short sprints, for example, 1 or 2 weeks, tasks sized at over 1 day should be broken down into smaller tasks for the purpose of sizing. <aside> Work out what you need to do first (it can change, but it’ll give you a good idea how big the whole thing is). What tasks are there? What concepts might the user need? What reference? Do you need to update other things? Are you doing embedded assistance? What do you need to update to ship the product, datasheets perhaps? How long does it usually take to make something new, to change whats there? To get it reviewed/tested etc? Don’t go overboard with the chunking – you don’t need to count the words, but the more you can say what you need to produce, the better your sizing will be. If it doesn’t fit in the iteration, put what you will do this iteration in the plan, and schedule whats left for the next iteration. Sanity check what you have listed with someone else. If it seems too big – what does the user really need? Do they need it all? Can you provide it in a different way?</aside>

OK, so your developers don’t do detailed design specifications anymore? Well you need to get your input another way. Interviewing is an obvious technique, and you probably have to do it now anyway. Another useful technique is pair-programming, sit down with the developer and get them to show you what they have done. This is actually a good technique if they are working on interfaces where they can get your input on terminology and label names for example, or when writing error messages – you help each other! It is quite common in agile for demos to be used to show progress to stakeholders and get feedback. Get into those meetings, it not only helps you to see how the software is working, but also the kinds of questions the stakeholders are asking.

Ideally in agile the team have some of the following documents to help them understand user requirements and needs better, these can help developers, testers, and writers:

The first is to define and understand user roles. For any given product there is likely to be one or more user roles that will use that product. Each user role will have particular tasks they perform or goals that they want to achieve. They may also have a set of associated skills, and they may work in a particular environment. Examples of user roles might be:

• Web developer
• Systems administrator
• Technical support officer
• Lab assistant

Personas are an extension of user roles where you create a fictional character that represents a group of your users. A persona typically includes the following types of information about the fictional user:

the user’s name and information about their age, education, experience, and possibly even include a picture and more demographic details.

• the user’s job title and major responsibilities are included, and details of relevant skills, and other related product use – for example, software, hardware, platforms?
• what their goals and tasks are with using your product, what is their organisation, why do they want the product, what’s the problem/business opportunity that it solves?
• the user’s physical and social environment. Where do they work, with what facilities, how many sites, how many people, how many servers, and so on?

A story is used to detail what a user wants to do with your product, or a part of your product. It describes just what the goals and tasks are, and not how a particular user might use the product.

Scenarios extend stories by using a specific user, for example based on a persona, to detail specific requirements that that user may have, or a specific way that this user uses your product based on their existing knowledge and experience, or particular environment. A story tends to focus on the so-called ‘golden path’. A user wants to achieve a particular goal, and the steps for them to do that are likely to be considered. With the scenario problems with the golden path may be highlighted, and alternate paths may need to be explored to support users with the same requirements as the persona.

Use cases are used to described the interaction of a user with a system (and sometimes system to system interaction). They provide the commonly expected way that a user uses a system, and what happens, but also problem conditions and alternative interactions.

User feedback is obviously valuable in improving the user documentation and also understanding the needs of customers. This can come from customers using released versions of the software and the documentation, from stakeholders representing the users, and from the other members of the agile team.

It is as important that the user documentation is usable and correct for the user, as it is that the software works and usable for them. The user documentation should therefore be reviewed (both for style and for technical accuracy), tested with the software for accuracy and for usability. When reviewing and testing it is helpful to have reviewing tools where comments can be added directly to documentation (for example like comments on this blog) so that the context is clearer, and others can easily see comments that have been made. In the same way that software can have demos, so can user documentation, and a useful activity is to run walkthrough meetings to review structure and content  with the agile team and your stakeholders. Updates can be made during or after the meeting. Pair programming is an excellent approach for system testing, this time working with a tester when they test the software. You can pick up steps that you may have missed, and encourage the tester to use your documentation when they use the product. Again, you can make changes live, or changes after the event. An important activity to carry out, even if not every iteration is a usability test, where you get a user or someone representing the user to use the software with the documentation. This tells you at what point the user needs to use the documentation, whether they can find what they are looking for, and whether there are changes you can make to help them with particular problems or expectations.

The sprint cannot end without the documentation approved as complete, or without arrangements made to carry over unfinished items. User documentation in draft form has to be ready with enough time for review and for edits to be made.

Translation and localisation can be tricky to do in agile, primarily because of the time constraints. Its difficult to write and then translate or localise within the same iteration. When planning, consider whether translated or localised versions need to be released at the same time as the software, and do they need to be included for each sprint? How much time do you need  – include for packaging, translating, handling returns, testing and integrating? If you need to do everything in an iteration, then prioritise the material based on  local requirements and regulations and the needs of the users. If you are able to, consider translating in one sprint, and incorporating in the next.

Finally, a useful tactic to make it more practical to fit everything into agile is to use consolidation sprints. These are sprints when development of new code is low, or more focused on code not visible to the users. For developers not involved in coding, these iterations can be used for translation of interfaces and messages, integration of different parts of the software, user acceptance testing and so on. For the writers these can be useful for some of the bigger picture items, such as user guides, concepts and references materials, integration, usability testing, and translation.

Yes agile can be a very different way of working, and that is scary, especially as the writing teams or individual writer often are at the mercy of decisions made by development teams. But there are benefits for individual writers, in particular the opportunity to raise their own profile, and the profile of the user documentation by working closely with the development teams, getting closer to users and influencing the design of the product itself.

A quick reminder about our standards. We’re hoping that ISO/IEC 26515 will be published next year. We’re on our final ballot. We also have a really useful set of standards for all those involved in producing user documentation. If you need some more weight with the development teams or think that the way you are working might not be ideal, or just want to know about best practice – take a look. You do have to pay for ISO standards, but if it makes your life easier its well worth it!

Check here for all the Sc7 standards that are published and being worked on. Check slide 35 for the numbers of our standards!

If you’re interested in reviewing our future standards and providing comments, please let me know your email address and I’ll pass it on to Richard (WG2 convenor).