The agile advantage

The Agile AdvantageThe Agile Advantage

Abigail SamuelAbigail SamuelInformation Developer, IBM India Software LabsInformation Developer, IBM India Software Labs

[email protected]@gmail.com

2

About this presentationAbout this presentation

The goal and objectives of this presentation are:The goal and objectives of this presentation are: To remove some perceived mind blocks about AgileTo remove some perceived mind blocks about Agile To highlight why technical writers should actually like AgileTo highlight why technical writers should actually like Agile To convert the challenges into advantages so that we can To convert the challenges into advantages so that we can

integrate more smoothly into an Agile development teamintegrate more smoothly into an Agile development team

The presentation covers the following topics:The presentation covers the following topics: Ensuring quality in technical documentation by using the Ensuring quality in technical documentation by using the

opportunities that Agile providesopportunities that Agile provides Tips for a technical writer in an Agile projectTips for a technical writer in an Agile project How Agile teams can leverage the expertise of a technical writerHow Agile teams can leverage the expertise of a technical writer

3

Key characteristics of quality documentation

Developing Quality Technical InformationDeveloping Quality Technical Information~ Ensuring usefulness, not just conformance~ Ensuring usefulness, not just conformance

Easy to findEasy to findEasy to findEasy to find

OrganizationOrganization

Visual effectivenessVisual effectiveness

RetrievabilityRetrievability

Easy to useEasy to useEasy to useEasy to use

Task orientationTask orientation

AccuracyAccuracy

CompletenessCompleteness

Easy to understandEasy to understandEasy to understandEasy to understand

ClarityClarity

ConcretenessConcreteness

StyleStyle

Timeliness (correct estimates and sizing)

4

Developing Quality Technical InformationDeveloping Quality Technical Information ~ using Agile to your advantage ~ using Agile to your advantage

Benefits for TWsQuality documentation




User storiesUser stories

VisibilityVisibility

FeedbackFeedback Test-driven developmentTest-driven

development

TW on par with dev and

test

TW on par with dev and

test

Collaborative environment Collaborative environment

Involved from the

beginning

Involved from the

beginning

AGILEOn-time deliveryOn-time delivery

CompleteComplete

ClearClear

Properly sizedProperly sized

EffectiveEffective

Task-orientedTask-oriented

ConcreteConcrete

UsefulUseful

OrganizedOrganized

RetrievableRetrievable

AccurateAccurate

MinimalMinimal

5

Tips for a technical writer in an Agile projectTips for a technical writer in an Agile project

Get involved

Increase product knowledge

Take the initiative

Add value

Establish formal review process

Plan tasks for hardening sprints

Implement feedback

6


Provide TW inputs during story-pointing or planning poker sessions

Results in more accurate sizing or effort estimation

Helps to better understand each story and its documentation requirements

Attend and try to participate in all the scrum activities and meetings

At sprint planning, the stories picked for the sprint, TW tasks, priorities are discussed

Be prepared to communicate your status daily during stand-up or scrum meetings

Use retrospect meetings to improve and establish TW process followed in the team

In sprint-end demos, provide inputs related to user experience, get doc feedback

Get involved

During design review meetings, include the documentation design for the feature

7


For every story or defect, ask if there is a documentation impact

Start writing in the same sprint with product development and testing

TW tasks need to be completed for story to be marked as “done” and to claim points

Use whatever design info is available, test cases, discussions, wikis, to get started

Put placeholders for gaps that can be filled up later

Tell team when blocked, need help or input, or have a dependency on their tasks

Re-define “done” criteria for user stories to include only authoring and tech review

Initiate discussions, clarifications, reviews (reminders)

Take the initiative

Have exclusive documentation meetings for user story

Keep your lists of questions and points to be clarified ready

8

All who are assigned to a user story and the team leads can be mandatory reviewers; rest of the team can be included as optional reviewers

Later technical review should be formal using a tool to track review comments and mark approvals


Have the initial review in the form of a demo or review meeting

Create a short checklist for technical review points

Establish a formal review process

Send out reminders for review if not done on time

9


Install, configure, and use latest builds when documenting

Increase product knowledge

Drive the terminology – standardize terms for consistency

Participate and provide inputs during UI design and reviews

Add value

Offer to work on material other than documentation (demos, articles, papers, etc.)

10


Accessibility testing, globalization, testing of deployed information, etc.

Schedule a “big picture” technical review of all information added / updated in release

Keep a buffer for making minor last minute changes before the release

Plan ahead for tasks to be done during hardening sprint

11


Feedback received in each iteration and milestone

Consumability improvement surveys

Enhance documentation to reduce support queries

Welcome and implement customer feedback

12


Information development process: task-oriented topic writing, minimalism, how reviews and will be done, tools used to track reviews

Methodologies: DITA and structured authoring – creating modular re-usable information units, single-sourcing and conditional processing of information

TW skills: organizational, interviewing and listening, ability to convey complex thoughts in a simple and clear manner, editing and language skills

Give the development team a behind-the-scenes tour of TW

Tools: Editing tool, Checking tools (for example, Acrocheck), Build tools, CMS, Accessibility testing tools (for example, JAWs)

Guidelines and standards: style guides, terminology standards, and other guidelines specific to our product division

13

Leveraging the expertise of technical writersLeveraging the expertise of technical writers

in meetings, training sessions, and demosin meetings, training sessions, and demos

when searching for specific documentation

when searching for specific documentation

Ask TWs

to organize, write, review or edit

information other than product docs

to organize, write, review or edit

information other than product docs for usability related

suggestionsfor usability related

suggestions

Consult TWs

by using docs when testing or trying out functions

by using docs when testing or trying out functions

Give feedback

all information that will be publicly exposed

all information that will be publicly exposed

Get TWs to review

Use TWs’ skills

Involve TWs

to set aside time for focused technical reviews

to set aside time for focused technical reviews

Planby copying them on all

relevant mailsby copying them on all

relevant mails

Keep TWs in the loop

14

ConclusionConclusion

Highest priority is to satisfy the customer

Highest priority is to satisfy the customer

User task-orientationIts not about what the software does

Its about what the user does

User task-orientationIts not about what the software does

Its about what the user does

Simplicity – the art of maximizing the amount of work not done – is essentialSimplicity – the art of maximizing the

amount of work not done – is essentialMinimalism – Think more, write lessProvide the right content, to the right

person, at the right time

Minimalism – Think more, write lessProvide the right content, to the right

person, at the right time

Quality (useful) technical

informationAgileAgile DocumentationDocumentation

15

Questions?Questions?

16

ReferencesReferences

Agile:Agile:

http://agilemanifesto.org/http://agilemanifesto.org/

http://www.scrumalliance.org/articles/369-a-writers-guide-to-surviving-http://www.scrumalliance.org/articles/369-a-writers-guide-to-surviving-

agile-software-developmentagile-software-development

http://www.writersua.com/articles/AGILE/index.htmlhttp://www.writersua.com/articles/AGILE/index.html

http://www.agilemodeling.com/essays/agileDocumentation.htmhttp://www.agilemodeling.com/essays/agileDocumentation.htm

Developing Quality Technical InformationDeveloping Quality Technical Information

http://www.ibmpressbooks.com/bookstore/product.asp?isbn=0131477498http://www.ibmpressbooks.com/bookstore/product.asp?isbn=0131477498

IBM Rational Team Concert (Agile project management software)IBM Rational Team Concert (Agile project management software)

https://jazz.net/products/rational-team-concert/https://jazz.net/products/rational-team-concert/

http://agilemanifesto.org/

http://agilemanifesto.org/

http://www.scrumalliance.org/articles/369-a-writers-guide-to-surviving-agile-software-development



http://www.writersua.com/articles/AGILE/index.html

http://www.writersua.com/articles/AGILE/index.html

http://www.agilemodeling.com/essays/agileDocumentation.htm

http://www.agilemodeling.com/essays/agileDocumentation.htm

http://www.ibmpressbooks.com/bookstore/product.asp?isbn=0131477498

https://jazz.net/products/rational-team-concert/

https://jazz.net/products/rational-team-concert/