technical writers in scrum teams

Pietro Margutti - Operans Project April 2008, STC-TAC Conference

Techwriters in scrum teams 1

Technical Writers in Scrum Teams

• Scrum !?!

• Software Development Models

• Agile Methods and Scrum

• Technical Writers in Scrum Teams

• Some Difficulties

• Conclusions

Scrum !?!



Scrum in rugby

• The method of beginning play in which the forwards of each team crouch side by side with locked arms

• Play starts when the ball is thrown between them and the two sides compete for possession.

[Source: http://www.thefreedictionary.com]

April 2008 - STC-TAC Conference - Techwriters in scrum teams 3

Coordination to govern the chaos and win

• Looks very chaotic

• In fact requires careful coordination in a stressful situation

• Each player has a specific role in the scrum

• The whole team plays, and the whole team wins or loses




Software Development Models

Development steps (part of overall lifecycle)

• Vision

• Marketing Analysis

• Technical Design

• Implementation (including user doc)

• Testing and Qualification

• Commercialization

• MaintenanceApril 2008 - STC-TAC Conference - Techwriters in scrum teams 6



Waterfall model for software development

• First defined in 1970by W.Royce, who started criticizing it

• Sequential model

• Often criticized but still very popular and widely used

• Applied against unstructured approach(cowboy coding or code-and-fix model)


Requirements

Analysis

Design

Coding

Testing

Installation

Maintenance

Analysis

Coding

Rigid waterfall procedures …

• Prescribe a perfect sequence of development steps: requirements, analysis, design, implementation, documentation, and tests.

• Are effective only when the phases remain stableand predictable during the entire process.

• Errors and modifications would cause unexpected and costly backward steps.




… and also:

• Establishes a rigid separation of roles & responsibilities

• Results in treating people as a factor of production

• Discourages cooperation across departments conflicts:- Marketing vs Technical dept: stability of requirements- Development vs QA: quality and usability of software

• Technical communicators always try to make peace,don’t we?


Criticisms to the waterfall model

• Requirements must be fixed before system design

• Design and code work often turn up requirements inconsistencies, missing components, and unexpected needs

• Late problem discovery during system testing

• System performance cannot be tested until the system is almost completed[Source: Internet Archive (web.archive.org)]




New models proposed, e.g.:

• Modified Waterfalls: overlapping phases / sub-projects

• Spiral model: breaking the project up into mini-projects

• Evolutionary Prototyping: refining prototype until OK

• Staged Delivery: incremental implementation

• and more ...

no model can be the best for all projects, it depends …

[Source: Steve McConnell, Rapid Development, Microsoft Press, 1996]


In the real world …


• Marketing requirements may change during the development process

• Users get to know what they really want only they see the first version of the software

• New tools and technologies can greatly influence initial implementation strategies

• Financial support to the project may cease if no visible result (running software) is shown



Defined Process Control …


• Theoretical models have failed in many non-trivial software projects

• Complex interactions and constantly changing conditions make software development too unpredictable for a theoretically defined approach

• Application of Defined Process Control does not ensure success

… or Empirical Process Control


• Guiding the process step by step

• Ensuring that the process progressively converges

• Introducing flexibility, adaptability, and productivity

• Moving focus from defined process to people tasks

• Govern the chaos!



Because that’s the real world


Agile Methods and Scrum



The Agile Manifesto


Important More important

Process and Tools Individuals and Interaction

Detailed Process Doc. Functioning Software

Contract Negotiations Collaboration w/ customers

Following a Plan Adapting to Changes

[Source: Manifesto for Agile Software Development, www.agilemanifesto.org]

Agile Methods


• Agile methods as reaction to processes that look good in theory but that often do not hold up in practice

• Empirical and based entirely on practical experiences and work methods that are proven to work

• Central concept is adaptation to change

• List includes: Extreme Programming (XP), Scrum, …

[Source: Scrum in five minutes, www.softhouse.se]



History of Scrum method (1)


• The New New Product Development Gamearticle by H.Takeuchi and I.Nonaka

• “What we need today is constant innovation in a world of constant change”

• Built-in Instability: clear goals but no fixed work plan• Self-organizing Teams, Overlapping Development Phases• Self control, control through peer pressure• Multi-level & multi-functional learning, learning transfer

History of Scrum method (2)


• Scrum method by J.Sutherland & K.SchwaberEnhancements by Mike Beedle

• Publication of Agile Software Developmentwith Scrum by Ken Schwaber & Mike Beedle

• … and thensuccessful use of Scrum in several SW projects



How Scrum works: the people


• A Scrum team is typically made up of five to nine full-time people, including a scrum master, various development and test engineers, and at least one technical writer

• A product owner, typically a product manager, knows what needs to be build and in what sequence this should be done

How Scrum works: the methodology


• The requirements are collected in a prioritized list, the product backlog, by the product owner

• Development is organized in short iterations, or sprints, focused on a selected set of high-priority requirements

• Sprints are planned in detail in order to deliver a working and documented product release

• The Scrum team works in close cooperation and meets every day (daily scrum) to discuss and resolve problems



The Scrum process


An important rule to govern the chaos


• No outside influence (management, product owner, …) can interference with the Scrum team during the Sprint Team members are committed to the goals (pigs), anybody else may be involved (chickens) and attend the meetings but not interfere!

• The Product Owner can change the Product Backlog at any time, but submit new priorities to the Team only during the Sprint Planning



Chickens and Pigs


[Courtesy of www.implementingscrum.com]

Scrum Room




Technical Writers in Scrum Teams

27

Opportunities

• At least one Technical Writer is part of a cross-functional Scrum team

• Our role is definitely more important and we can follow the development of new products right from the start

• Project visibility: we become part of the transfer of learning

• New job opportunities for techwriters in Scrum projects




Basic Tasks

• Ensure that the documentation tasks are properly defined at the beginning of each Sprint

• Define the terms of documentation completeness

• Attend and participate actively in relevant meetings

• Complete the documentation tasks in the sprints

• Keep the global documentation release in mind


New tasks

• Opportunities beyond our classic job profile

• User Stories (Agile methods)

• Use Cases (UML)

• Usability studies

• Scrum is channeling creativity in focused and productive ways




New capabilities

• Formal languages, UML - Unified Modeling Language

• Knowledge of software engineering standards and techniques

• Develop sufficient skills to actively follow the daily meeting with software specialists and to interact with them effectively

• Information may not be available in formal specifications


Best Practices: Bottom-up vs Top-down

• Scrum teams deliver incremental releases: product (and documentation) starts from a small subset and then grows progressively

• While staying focused on the individual features being released, we should use our experience to keep in mind the big picture, i.e. the final documentation targets.

• Bottom-up implementation should be integrated by a top-down design




Best Practices: Technologies and Methods

• Using topic-oriented approach (e.g. XML, DITA)

• Leveraging user stories to produce task-oriented documentation

• Applying minimalist principles

• Participating as an active team member

[Source: T.Berry, A.Gentle, Writing End-User Documentation in an Agile Development Environment, CIDM June 2006]


Best Practices: Topic-oriented approach

• Modular approach perfectly suits scrum development

• From a unique narrative flow (book-oriented) to cohesive, self-contained, re-usable elements

• Authoring templates and structures for guiding authors to answer basic questions: “What is…”, “How do I …”, “What went wrong …”

• Maps / Sections / TOC design guides the assembling




Best Practices: Task-based Documentation• User documentation can follows the User Stories of the

agile analysis techniques

• Identify the user(s)

• Look at all the ways in which the user(s) might need to work with the product

• User tasks as key elements around which creating concept and reference material (DITA)

• Task orientation helps applying minimalist principles


Best Practices: Minimalism

• Learn at using new technology: From the legendary funnel of Nurnberg (texts by J.Carrol) to the fast training session in Matrix movie

• Plain instructional solution to learning problem

• The learner, not the system determines the model

• Not only less words, but the right words

• Writing / translating / maintaining costs




37

Some Difficulties

The Scrum World

• Full-time office job, difficult to work at home

• Daily scrum meeting: what did you do yesterday? what do you plan to do today?

• Continuous personal interactions

• Peer control, each participant sharing success or failures

• No more privacy, uncomfortable visibility




A Cultural Clash

• Typically lone writer in the team

• Sort of alien in the technical team

• Initial exclusion: “we do not have anything for you to document yet”; “we do not need you in the Scrum yet”

• Communication difficulties, technical jargon or terminology


Collecting information

• Incomplete or missing specifications:some technical document may be optional in Scrum

• Technical details are discussed in meetings and not formalized

• Preliminary and unstable software

• Rapidly changing design




Short schedules

• Short delivery schedules: product release become monthly iteration release

• Detailed tasks estimations

• Timesheet reporting by the hour

• After a while, team may be very productive, hard to keep up


Estimation skills

• Activity planning and tracking is very detailed during the Sprints

• Activity reporting is public knowledge

• Keep detailed track of time spent for each activity

• Difficulties can be an opportunity to improve our estimation skills

[Source: C.M.Sigman, Adapting to Scrum: Challenging and Strategies, Intercom July 2007]




Basic Survival Kit (1)

• Attend the daily Scrum and all relevant meetings

• Take an interest in all of the work being done

• Contribute beyond the job assignments

• Play with the team, be an active member and get the confidence of the others, …


Basic Survival Kit (2)

• Learn how to control the flow of documentation work

• Try to avoid that all work arrives in the final week of the sprint

• Define the exact documentation goals for each sprint

• Include documentation design in the sprint planning

• Agree if documentation can lag behind one or more iterations




45

Conclusions

A new working environment


• Cross-functional team: do we want to be part of it?

• Creative, lively, and empathetic environment

• A lot to learn and quite a bit to teach

• The key of success if the active participation

• Encourage and embrace face to face communication



That’s it!


Questions? Comments?

Ask now or contact me later at:

[email protected]

References


Articles• W. Royce , Managing The Development Of Large Software Systems, in IEEE WESCON Proceedings, Aug 1970• H.Takeuchi , I.Nonaka , The New New Product Development Game , in Harvard Business Review, Jan-Feb 1986• C.Sigman, Adapting Challenges and Strategies to Scrum , Intercom magazine Jul-Aug 2007• T.Berry, A.Gentle, Writing End–User Documentation in an Agile Development Environment, CIDM, Jun 2006

Books• P.DeGrace , L.H. Stahl, Wicked Problems, Righteous Solutions , 1998• K.Schwaber , M.Beedle, Agile Software development with Scrum, 2001• David Churchville, Agile Thinking, Leading Successful Software Projects and Teams, 2008• J.Carrol, The Nurnberg Funnel: Designing Minimalist Instruction for Practical Computer Skill, 1990• J.Carrol, Minimalism Beyond the Nurnberg Funnel, 1998

Web links• www.implementingscrum.com www.scrumalliance.org• www.agilemanifesto.org www.controlchaos.com• www.rapidinnovation.ning.com www.infomanagementcenter.com

http://www.implementingscrum.com/

http://www.scrumalliance.org/

http://www.agilemanifesto.org/



http://www.rapidinnovation.ning.com/




http://www.scrumalliance.org/

technical writers in scrum teams

Documents