Technical Writing in Agile: New Approaches, New Opportunities

Editor's Notes

• #2: We’ll look at what agile is….….and a few things that it isn’tWe’ll explore what agile means to the tech writer….and to the project managerThen we’ll talk about opportunities for tech writers, that agile offers
• #3: Agile, or “Just in Time” development, began as a software methodology but is likely to gain acceptance in other industries as well. Emphasizing flexibility and responsiveness to customer requirements…… agile is characterized by:Short product cycles, made up of sprintsProduct updates are smaller, shipped more frequently
• #4: Continued…Products and documentation are often shipped before being thoroughly tested and editedThis practice is based on two assumptions: Customers are eager to get the new materials as quickly as possibleAny errors or bugs can be fixed easily in the next updateWritersUA 2014 Tools & Skills survey (Joe Welinske):57 percent of software tech writers are working in agileThis percentage has soared in just the last few yearsAgain, I foresee this practice gaining acceptance in other industries besides softwareIn this age of social media, companies are eager to be seen as responsive to customers’ needsAlso, companies are reluctant to sink huge investments in a project……without knowing whether it’s going to succeed in the marketplace
• #5: Agile is a methodologyIt’s not:A new set of tools – you won’t have to learn new tools, or give up the ones you’re usingA new way of writing code (a new programming language)Just a new name for what you’re already doing (despite the Dilbert comic)The old way we did things is known as WaterfallStart with a comprehensive planStick to it, no matter whatNew way: Start with a short-term planExecute the plan….….Then reassess and make another short-term planIt means learning a different mindsetIt also means that people need to be trained in the methodology (People need more training than Dilbert & Wally are getting here)
• #6: The agile manifesto was developed by a small group of software engineers in the early 2000sWe are uncovering better ways of developing software by doing it and helping others do it. Through this work we have come to value:Individuals and interactions over Processes and toolsAgile is highly team oriented (the scrum team)Working software over Comprehensive documentationExplain that documentation means design documents and specifications– not necessarily manuals and help topicsTrue, trimming unnecessary customer documentation is very much in the spirit of agile…….But no one is saying that user guides, etc., have become expendableCustomer collaboration over Contract negotiation1. Frequent interaction with customer community…….Rather than talking with them once and going off and building a product2. Frequent interaction among the various project stakeholders: R&D, QA, Tech Pubs, MarketingResponding to change over Following a planAcknowledges that circumstances and customer requirements can changerapidlyPlans are good, but not if they’re inflexible I hope you’re thinking, “this makes sense”This is a realistic way of looking at today’s business worldIt’s highly customer orientedIt minimizes waste
• #7: Let’s define some of the terms that you’ll hear in agile:User story: A set of customer requirements, usually oriented to a specific product featureIf you’ve done task analysis, especially usingpersonas, this is the same kind of analysisUser X [persona] is will use the product to do Task Y in such-and-such fashionSprint: A single development cycle: Develop, test, and document a small number of features, start to finishUsually takes 2 to 4 weeksScrum: The team, and more broadly the framework under which the team operates(In other words, you’ll hear the process referred to as “scrum”)The team meets daily, like in a rugby huddleThen it breaks the scrum and swings into actionBacklog:The list of requirements for the productIncludes user storiesAlso includes other essential activities, like doc and translationRelated: The burn down chart: a graph showing the remaining backlog (work left to do) over timeLooks like a downward slope – useful for tracking progress against planStand-up meeting: Some team leads (scrum masters) ask everyone in the meeting to remain standingThis ensures that things will move quicklyThe idea is that scrum meetings are short and productive(Some people even stand at their desks while attending by conference call)In “pure” agile, each member reports 3 things in the stand-up meeting:• What I did (since the last scrum meeting)• What I’m going to do next• Anything that’s blocking my progress – e.g., I need a new software driver from Joeor I have a question for the team
• #8: In agile, quality is defined by what meets the customer's expectations ("user stories")When the user story is: User A needs to do Task BSuccess is defined by: Can User A successfully complete Task B?That means that quality isn’t defined by things like good writing and good designThose were the old metrics that we used (or thought we were using……We were never able to measure those anyway)I’m as old-school as anyone when it comes to viewing writing as a craftI’ve edited and re-edited my copy and tried to fly as close to the sun as possibleBut I’ve had to learn that the test of quality is in the results, not in the product itselfPut another way: if your user guide keeps customers from having to call Tech Support……it doesn't matter if it's printed in 6-point type on the back of a brown paper bagIt's a good user guide.Also:Everything we publish can be revised and republished in an instantEven a PDF can be updated and repostedSo why wait until it’s perfect? Why not get content into the customers’ hands quickly? If later I find a typo, or if the part number for a thingumabob changes……. I can make the update with a simple click(At end of this webinar I’ll show a link to my blog article Good, Not Perfect)
• #9: "The Big Shift" - Jason PolitesYes, agile requires a new way of thinkingYou don’t just come to work one morning and start working in agileAll participants – writers, developers, everyone – need to be trained in the new mindset"Focus is the invisible guide"Agile demands a shift in thinkingFrom "do I have time for this?" [schedule orientation] To "what's most important?" [priorities based on customer requirements]Forget datesNow it’s all about customer requirements (user stories)
• #10: Because agile relies on short product cycles and not on long-range plans….….Some aspects of your life as a technical writer will change• Technical reviews are often ad hoc and very limited in scope.• Pre-existing or legacy information is easy to overlook….…. increasing the risk that outdated material is included in the final documentation.• Editors have less time to edit documents (sprints are short in duration)….…. and they frequently have to do piecemeal edits rather than seeing the documentation as a unified whole• Translation is harder to scheduleBecause development cycles are shorter, and plans aren’t made months in advanceAlso because translators, like editors, often don’t see the documentation as a unified whole
• #11: There are not always any easy answers….Even if the project team has decided that agile is right for them….….there might be times when you need to do things in an un-agile waySo even though agile might sound like something totally new and terrifyingTake a deep breath – relaxMany aspects of your work won’t change – and some aspects will actually get betterThe best advice (per Alyssa Fox): be flexibleBecause, let’s be honest:Were reviews, legacy information, editing, and translation always problem-free under the old Waterfall methodology?You’ll still have problems in agileBut they won’t be worse than anything you’ve handled beforeAnd in many ways things will be easierEspecially when you’re flexibleJust like the happy writer you see here
• #12: Four Must-do’s to Become a Key Agile Team Member [Alyssa Fox in TechWhirl - Jan '14]Because agile emphasizes personal interactionAnd because attention shifts from product features to the customer experience….The technical writer becomes a more integral part of the product teamThis is an opportunity you simply can’t pass upSo here are the four ways to be an effective team memberSpeak UpAgile emphasizes the team – so become a full memberSpeak up!Speak up for the people who use the productSpeak up to get the information and the access you needAsk lots of questions, and as your knowledge increases, use it to contribute to design discussionsSpeak up, and in detail, at scrum meetings: Scrum is a give—and get—detailed forum for exchanging informationGood example: “I am almost done creating the help structure for the X wizard. Developer Sally, I’ll need to show you what I did in the mapping file.I’m also adding these topics to the .chm file’s table of contents.”This example is:SpecificIdentifies what you need Who you need it fromGet Involved in All Areas of DevelopmentAgain, you’re now a full part of the team, not shunted off to the side“I’m just the writer” won't wash (these are the worst words ever!)You gain "street cred" by showing an interest in the product design, offering to improve the GUI, etc.Alyssa strongly recommends the whole team approachEvery sprint includes all phases of the project – dev, QA, and Doc(Avoid “done” and “done done”: code first, then doc later….….This approach tends to result in docs – and the people who write docs – getting shunted to the side)Take Ownership of Technical AccuracyKeep in mind that you’re leading the documentation effortDon’t settle for writing what the developers tell you to write Don’t assume something works a certain wayChallenge and validate assumptions by asking questions, and testing buildsHave your own set of virtual machinesUnderstand the product (product knowledge earns you the trust of the other team members)Serve on a “Core” TeamA core team consists of a lead from each functional area (Product Management, Development, QE, Info Dev, and Technical Support)Makes project decisionsHelps each functional area get a “bird’s eye” view of how all the product components and support systems work togetherTo net it out:You have an opportunity to exert more influence than ever beforeTake it!
• #13: For the PM, as for the writer, agile represents a new way of looking at thingsSo don’t be like Dilbert’s boss: Agile is NOT a just new name for old management techniquesDifferences for the PM – Old – waterfall: Project is set in motion, and then it just moves along – like water going over a cliff(Some would observe that the movement is always downhill, but I won’t observe that now)Agile: Project is set in motion, but it can change course as it goes alongI like this way of looking at it:R. Stephen Gracey (@rsgracey, or the Content Strategy Noob): Scrummy Content in an Agile World – (URL on Resources slide)Key point: You never really could plan in waterfall, either - you just THOUGHT you couldGraceyasks whether youhaveto apply waterfall principles when implementing a content strategyAfter all, he reasons, doesn't the content strategist have to know the big picture in advance? Isn't that "waterfall," almost by definition?Agile seems to go against the desire for a unified approach to content(Continued)
• #14: It's well worth reading the progression of Gracey’s thoughts as he comes around to adopting the agile viewI won’t get into all of it hereBut I’ll mention two of his main points:First, you have to go all in – either waterfall or agileYou can’t try to blend waterfall and agile – the two are diametrically opposedThe point I like best, is the one Gracey saves for lastAre you worried about the uncertainty involved in managing an agile project?Guess what? if you thought you could manage projects in waterfall, you were only kidding yourself – Especially in terms of planning big projects so that they'd meet schedules There are just too many unknowns, too many things that change along the wayThe best content strategy -- and, for that matter, the best project plan –…. isn't the one that strains every gnat and makes sure that every eventuality has been considered and covered. Instead, it's the one that provides strong, overarching principles that can be applied to every eventuality.Agile and Scrum accept the ultimate truth that no system can be controlled or predicted as long as human beings are involved.Instead, by breaking the work into short bursts, emphasizing conversation and regular inspection……and accepting change as inevitable, it becomes possible to:Minimize the long-term impact of inevitable mistakes.Take full advantage of humans’ creativity and inventiveness.Move forward without being paralyzed by uncertainty.
• #15: OpportunitiesTech writer has greater voiceMore often you’re seen as an equal member of the teamI talked about this earlier: Speak up, contribute in new waysTech writer takes the lead in creating user storiesWhy not? We’re well versed in audience analysisWho better to describe who our customers are, and how they use the product?By developing user stories, we give ourselves a vital role in the process(Since agile development is centered around user stories)(Continued)
• #16: Opportunities (2)Everyone contributes contentWriters aren’t the only ones who contribute content – part of our role shifts to curationCuration – like a museum curator – someone selects which content is placed on display, and how it’s presented to the audienceOn several agile projects, developers are contributing more content for the documentation -- especially, for example, API reference topics. We're also seeing the evolution of tools……Making it easier for developers to contribute well-formed content without having to learn tools like FrameMaker or processes like DITADoc-only sprintsSome teams hold documentation-only sprints, with a project backlog consisting solely of documentation tasksThere seems to be little consensus -- yet -- on whether this is an effective strategy(My own guess is that it’s not as effective as the whole team approach that I mentioned earlier….….in which docs are developed in parallel with the product…….the scrum team is likely better able to focus on all relevant areas of the doc)To help get buy-in, one PM has even developed a form, the Document Impact Notice (DIN), that sets out exactly what's covered in these sprintsSo….Not enough data yet, but something that’s being tried(Continued)
• #17: Opportunities (3)Agile provides cover for moving to topic-based writingYou can’t write monolithic books and help systems….….When the product is being developed a little at a timeSo you have to develop the docs a little at a timeTopic-based, modular documentation is almost a necessity on agile projectsOne correspondent mentioned that agile actually provided the impetus for her team making the move to DITAIf the team is shifting to a new way of thinking for agile…….They’ll likely be open to shifting to the new way of thinking that structured authoring entailsAct like a contractorWhen writers are spread too thinly among scrum teams, it might be necessary to pick the ones that are most critical and focus on thoseAs a TW, you have to act like a businessman (or woman)…….even if you’re a traditional “captive” employeeEstimate your timeStand up and say when you lack time or resources, or when someone isn’t meeting a commitmentUnderstand that assignments will be short-term……Gone are the days when you’ll work on a single set of docs for 6 to 9 months (or longer)
• #18: To sum up, here’s what the agile world is likeGone is the “security” of long product cycles….….When you knew what you’d be working on for the next several months(Really, how “secure” were those anyway?)So you’ll work on different things – no time to get boredYour work is much more geared to customer requirements [user stories]If you’ve ever wanted to be closer to the customers, agile is good news for youYou have a greater voice in thingsIf you choose, you can be an equal member of the project teamYou’re the expert in creating user stories and in writing good documentationHaving a greater voice means having more responsibilityYou have to speak up when you need something – or when you have ideas to contributeYou have to manage your own time and resourcesAgile is not for the lazy!
• #21: Contact information