Blog Archives

Introduction to agile methodologies

This week I attended a short introductory session to agile methodologies. An Atlassian colleague, Stuart Bargon, gave us a great overview of Scrum, Kanban and Extreme Programming (XP). We also had a brief discussion about how we can improve the integration of technical writing into the agile development process. These are my notes from the session.

To kick off the session, Stuart asked us what we already know and understand about agile methodology. There was an interesting range of answers:

  • One of the technical writers has documented GreenHopper for a year and a half, and therefore understands agile as a use case for that tool.
  • Another person went into details of the scrum and issue tracking procedures he’s experienced in the development teams.
  • Someone else had read the Agile Manifesto and understood the aims, but had never put it into practice in a team environment.

The Agile Manifesto

Stuart discussed each of the principles of the Agile Manifesto, illustrating some of them with examples from his own experience.

  • Inevitably, we dwelled a while on the point about “Working software over comprehensive documentation”. We didn’t come to any specific conclusions though, other than that everything is relative.
  • I said that my favourite principle, and one I think Atlassian does really well, is: “Build projects around motivated individuals. Give them the environment and support they need, and trust them to get the job done.”
  • Stuart pointed out that this one is particularly relevant to technical writers, in that it emphasises the diversity of skills amongst team members: “Business people and developers must work together daily throughout the project.”
  • Another one relevant to us, in our role as technical communicators: “The most efficient and effective method of conveying information to and within a development team is face-to-face conversation.”
  • Concerning the point about self-organising teams: “At regular intervals, the team reflects on how to become more effective, then tunes and adjusts its behavior accordingly.” Stuart pointed out that this is not a licence for a free-for-all. From a management perspective, the idea is to create an environment that gets the team to organise in the way you want it to. People are more motivated if they decide they want to do something themselves.

I found this point interesting: Many of the ideas in agile methodology come from the way Toyota works. In particular, Toyota’s teams regularly stop and examine their work to see how they can improve the quality. See the book “The Toyota Way“.

Agile disciplines

These are the methodologies we touched on:

  • Extreme Programming (XP) – a set of processes
  • Scrum – a lightweight process
  • Kanban – an even more lightweight process

Generally, agile practitioners pick and mix these days. They take bits out of the various disciplines to suit their needs.

Extreme Programming (XP)

We touched on the principles of Extreme Programming. It’s important to note that not many people follow all the principles devotedly. Instead, people take the bits they need. See this diagram of the Extreme Programming project.


Stuart ran through the basics of the Scrum process:

  • Write feature requests as “stories”. You should include the specific persona and the reason that persona wants to perform the task specified.
  • The “product backlog” is the list of stories in order of priority. Stories at the top of the list should be small. The stories at the bottom of the backlog tend to be just ideas and perhaps still rather big chunks. They must be broken down into smaller stories as they approach the top of the list. Some people use the concept of an “epic” to group related stories and keep them together as they approach the top of the list.
  • The “sprint backlog” is the list of stories to be tackled in a particular sprint.
  • The “sprint” is a period (often two weeks) during which the development happens. There’s a planning meeting at the beginning of the sprint and a retrospective at the end. The idea is that each sprint delivers a potentially shippable product.
  • Scrum defines 3 roles: The product owner creates and prioritises the backlog, defines the stories, decides what goes into the next sprint. The scrum master works with the team day to day and is focused on the current sprint, fixing anything that’s stopping the team from working. The team does the development work.
  • When estimating the stories, you try to use the idea of “story points” rather than time. The story points are expressed as a number, based on the relative complexity of the work required.
  • You work out your “velocity” based on the number of points that you have managed to complete during the sprint. For example, if you had an estimate of 10 points for the stories in a sprint, and completed 8 of them during the sprint, then your velocity is 8. You can work out an average over a number of sprints, and use this to compile estimates for your product backlog.

Stuart gave us a number of good sites for information about Scrum:


Stuart remarked that the processes of Kanban are even simpler than Scrum.

The first step is to map the workflow of your development team. Stuart drew a number of columns on the board:

  • Scheduled
  • In development
  • Ready for QA
  • In QA
  • Ready for deployment
  • Deployed (Done)

You then set limits on the columns, determining the number of cards (tasks or issues) that can exist in a column at the same time. For example, the above set of columns might have these limits: 4, 2, 1, 3, 3.

A good guide for setting the limits on the number of cards is the team size. For example, if you have 10 team members, the total number of limits across all the columns should add up to 10.

The idea is that anyone can write a story and put it on the board. You can reorder the items in the “Scheduled” column.

A developer takes the top card from the schedule and puts it into the next column (“In development”). When development is finished, the card moves into the next column (“Ready for QA”).

But you can’t put a card into the next column if the column is already full.

If a card cannot move into the next column, that means that the person who wants to move it must first tackle one of the cards in the column that is blocking the flow. In this way, the work flows through to the last column. Nothing has any value until it’s in the last column. There’s no value in the whole process unless it’s producing a number of cards in the “Done” column.

One of the attendees remarked that Kanban probably requires more behavioural change than Scrum.

Cards: Agile in a Flash

Stuart took us through some of the cards in a pack called “Agile in a Flash”. I’ve found these links referring to the pack: The Agile in a Flash blog and the entry on O’Reilly Media.

The cards cover the principles of standup meetings, retrospectives, values and principles, coding standards, code ownership, test-driven development, story prioritisation, why you would want to use agile methodologies, and more.

Story prioritisation

We took a quick look at how you prioritise stories.

  • First triage the stories. Assign story points, rather than trying to prioritise the stories in order of importance/desirability first.
  • Break them down into smaller stories if necessary to fit into a sprint.

Stuart told us a funny story of a developer who had tried to break a story into smaller stories. The story was a web form that was rather long, with may fields. He broke it down into a number of stories, each containing just one or two fields. Instead, he could have produced the whole form in one sprint, but with less complex validation and business rules. The first approach makes it difficult for testers and technical writers to do their work within a sprint, because there is no story that contains the entire form.

Stuart also discussed ways of prioritising stories by putting them in a quadrant, with axes such as complexity and business value.

In a sprint, it’s best to do the high risk things first because then you can deal with any issues that come up.

Contact with customers

Contact with customers is one of the agile ideals. It’s interesting to note that, as technical writers working at Atlassian, we have quite a bit of contact with customers. We work on a wiki, where people comment on our docs. They also see our names and email addresses on the docs, and email us directly. And they can make requests of us and the development teams via our public JIRA issue tracker.

How can technical writers work within the agile framework?

We didn’t have time to discuss the specifics of how the different product teams work, and how we technical writers can better integrate our work into the processes. Just a few general comments came up.

  • Log the documentation issues in the development team’s issue tracker.
  • Get rid of the lag: the scenario where the technical writers develop the documentation after the developers have finished their sprint. We had a bit of a discussion of the obvious challenges: Things do change during and after the sprint, so the technical writers will need to keep up with the iterative process too.
  • Push back and insist that the developer teams finish stories in a sprint, because otherwise it makes it difficult for the technical writers to do their work.
  • Sit down with the scrum master, explain the challenges and discuss the solutions.
  • Highlight any problems during the retrospective.

We discussed the idea of getting the documentation included in the “definition of done” for a development issue. There are pros and cons. For example, a pro is that the development team will be more aware of the work the technical  writers are doing and of what needs doing. A possible con is an increase in the tension between the development and the technical writing teams.

Stuart mentioned that in an agile team, there’s less of the idea that a team member is a specialist. Rather, each developer can work on any story. This could also work with the technical writers when embedded in the teams. The technical writers can give more input during planning meetings, into the design of a feature and how it will affect other parts of the product. Similarly, developers can do the drafts of the documentation to ensure it is all finished within the sprint. If you use a task board, such as in GreenHopper, you can see quite clearly the stages that the various stories are in. If a number of them get stuck in the “documentation” phase, that will be clear to the entire team. Therefore people will be more likely to jump in and grab a documentation task off the sprint backlog.

Agile pairing

Introduction to agile methodologies

I took this shot a few days ago, of two dragonflies locked in passionate embrace. They don’t look very agile, do they? Actually, they zoomed around quite efficiently, even in flagrante delicto. That’s agile pairing for you.

In conclusion

It was interesting to hear a summary of agile methodologies from an expert in the field. As someone who lives and breathes agile, Stuart was able to condense the essentials into a very short session and add some great titbits of personal experience too. I’m looking forward to the next session, which will cover specifics of the processes followed by the Atlassian development teams. We will discuss how we can better integrate technical writing into those processes. Thank you Stuart for a very useful introduction to agile methodologies.

Update: A few hours after I published this post, Mary Connor wrote an awesome post over on Clever Hamster, entitled How does Agile affect documentation? If you’ve got to the end of my post and want to take the next step, Mary’s is the one for you.

The agile technical writer II

In my previous post, I promised a braindump of the things our team has learned over the last months as technical writers in an agile environment. So here goes.

First of all, the agile turtle has had a makeover:

The agile technical writer II

Thanks to Ryan, who was totally mortified at my previous clipart mix-and-mashup.

So, what are the tips and techniques? They’re not rocket science, and they’re not so very different from what tech writers do every day even in non-agile environments. The main thing is an eagerness and enjoyment of going with the flow.

Stay on the hop and she’ll be right, mate.

Off on a tangent: I tried some chocolate beer last night. It was ~interesting. But that’s not the kind of hop I’m talking about here.

OK, let’s go:

  • Attend the development team standups (short meetings held standing up). This way, you get advance notice of new features, patch releases and changing deadlines.
  • Let the development teams know what you’re working on. Your work will dovetail with theirs quite neatly. I often find that I’m tackling a problem area in the documents (e.g. LDAP integration) at the same time as the developers are completing enhancement requests and the support team are weathering a storm of problems around the same topic.
  • Keep your contributions short at the standups. It’s a bit of a balancing act: some developers think you’re wasting their time. That’s not unique to the agile environment though. Not everyone is in on the secret that documentation is actually at the centre of the universe 😉
  • Make sure that the documentation is seen as part of the product, and that your development timeline is factored into the product release. Again, this is tricky — I’ve worked in places where this is seen as merely a nice-to-have.
  • Get with the eat your own dogfood thing. It really works. If at all possible, make the products you’re documenting part of your daily life. That might be difficult if you’re doing the techdocs for NASA or MI6 or something. But hey, a flaming rocket or a poison pen might just come in handy at the next standup 😉
  • Think like an engineer. When documenting a new feature, evaluate the end-user’s experience while writing the ‘how to’ stuff. Does it actually work for them? Remember that your feedback is valuable. Often, you are the first end-user-type to use the software, and you (or your documents) frequently have more of a big-picture and procedure-oriented view than the developer who wrote the code.
  • Apply the principle of iterative development to the documentation as well as to the software. Contribute to the QA and testing process, and be ready to adapt the documents to reflect any resulting code changes.
  • Subscribe to blogs, wiki watches and anything else that’s going. Some people may tell you that you’ll die of IO (information overload). But that’s not so. You’ll quickly learn how to scan the stuff coming in and pick up on the relevant bits. It’s the only way to stay ahead of the agile environment.
  • Seek even more input! Attend impromptu and scheduled training sessions. Attend the planning session which usually happens at the first iteration in each major release cycle. Keep your eyes, ears and antennae tuned for any other sources of information.
  • Respond to requests from customers. They may come at you via email, phone, comments on your documentation pages, etc. If the comment is about the documents, that’s your job. If not, pass it on to the support team.
  • Monitor the bug-reports and enhancement requests coming in for the product. Take note of any that will affect the documentation.

And here are two brand new techniques which our team has just begun trying out:

  • Swaparoo: In our team, each tech writer looks after three products. To get some cross-product knowledge going, we’ve started swapping tasks. One of us might announce in our daily standup that she is available for a swaparoo. The others will look for a suitable task that’s currently assigned to them. It might be a new feature for the next release or a meaty maintenance issue. And then the two writers will work together to get the job done. This is very like the ‘pairing’ that agile developers do. We just like the word ‘swaparoo’ better.
  • Code reviews: Get yourself included in the code reviews for major updates. Our company uses Crucible, a tool which allows engineers to embed their code reviews into the code and share the review comments with any number of people. The developer can assign a group of people to take part in the review. The tech writer can pick up some useful tips here too, just by watching the review comments whizz by.

And then, find some time to do a bit of writing.

The agile technical writer

One of the four basic principles of the Agile Manifesto is to value ‘Working software over comprehensive documentation‘. Oooo-er! Documentation devalued — that cuts technical writers out of the loop. Or does it?

Hallo, I don’t think so 🙂 The technical writer’s role has become even more interesting, exciting and above all, valuable — that’s what I find, anyway, now that I’m working in an agile development shop. And we’re extremely agile. We have seven core software products plus two hosted platforms, making nine products in total. Each product has a release cycle ranging from a couple of weeks to three months, give or take an iteration. That keeps us all on the hop.

The main thing is that you have to be, well, agile. This blog post is all about the Agile Technical Writer, even the Extreme Tech Writer — let’s call her the XTW.

The agile technical writer

Here is the preamble from the Manifesto for Agile Software Development:

We 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 tools
Working software over comprehensive documentation
Customer collaboration over contract negotiation
Responding to change over following a plan

That is, while there is value in the items on the right, we value the items on the left more.

I’ve found that the aim of having less comprehensive documentation applies primarily to the beginning of the traditional SDLC (Systems Development Life Cycle). In an agile development team, there tends to be a less comprehensive process around the feasibility study, business requirements investigation and functional specifications. That’s typically the domain of a business analyst rather than a tech writer, though the roles are very similar and often intertwine in very interesting ways.

A technical writer’s strengths really start to shine at a later stage, after the developers have had a first stab at writing the code. For the XTW (agile/extreme tech writer, for those who’ve just tuned in) this means that our role is even more interleaved with the business analyst and quality assurance roles. But it’s a matter of emphasis rather than a change.

The emphasis is on responding to our readers’ needs and producing high-quality products.

It’s just good fun as well as good sense.

A day in the life of an agile technical writer

  • Get in early and hook up to my feeds — see what’s happened to the documentation wikis while I’m asleep and the other side of the world is at play.
  • Trickle around the standups (short meetings held standing up), first with a development team or two and then with the tech writing team.
  • Play with the products and write the documentation.
  • Click on a flashing IM (instant message) from a developer who wants some advice on the text for an application screen.
  • Attend a super-short presentation by the development team of a new feature that needs documenting for the next software release.
  • Weather an IM blizzard from a support engineer half-way across the world, who has a customer with some interesting (synonym for irate) feedback on the documentation.
  • Try out a new feature and report behavioural quirks to the developer. The tech writers are often the first ‘real’ people to try the new feature. (Everyone knows that developers reside primarily in virtual rather than meat space.)
  • LOL in response to an IM from a fellow tech writer, who has spotted one of those things that only tech writers find funny.
  • Take a look at comments rolling in from customers on my space watch. People often put very useful comments on the documentation pages, which we can incorporate into the page. Other comments, usually by some dude called ‘Anonymous’, are not so constructive and may even need radical elimination.
  • Have a quick chat with a developer in meat space, to find out what bits of new functionality I might have missed.
  • Respond to a software emergency: Add a note to the wiki about a just-discovered bug in the latest release, give the stressed developer a chocolate and start the release notes for the patch.
  • Add myself as a ‘watcher’ of a just-reported bug that will require a documentation update when the issue is resolved.
  • Go and play with the WII in the lunch room.

‘Today I bought a bikini’, or ‘What about procedures?’

Myself, I’ve never been keen on procedures. If you’re going to do XTW, it’s more rewarding to go all the way. It’s a bit like buying a bikini (as I’ve just done today): the skimpier the better, otherwise it just doesn’t work and what’s the point anyway.

The agile technical writer

We’re a team of four writers. We have a wiki, where we put our guidelines and other interesting titbits. Did you know that Americans spell the last word in my previous sentence as ‘tidbits’? After writing the word, I realised that it might have an unfortunate association with the topic of the previous paragraph and picture, and I even contemplated changing the spelling. Is that why the Americans did? 😳

Rather than stating ‘This is how things are done,’ our guidelines are more along the lines of:

This is what’s working for us right now.


Hey, this is awesome, you might want to use it too.

A while ago 😉 a dude named Ovid said that everything changes and the only constant thing is change itself. He wrote a book about it, called The Metamorphoses. In his world, the situation was a bit out of hand. People changed into trees if they stood in one place for too long, gods transformed themselves into swans to fool a passing virgin, and the meringue of civilisation constantly threatened to crumble into wisps of sugar-coated nothingness.

Things haven’t changed much since then. (Paradox alert!)

I’d say that’s the main reason why the Agile Manifesto works. Things change, and we need to change with them. If we spend too much time setting requirements in stone, they’re out of date by the time we write the software. And then there’s no hope that the documentation will be up to date.

As a team of XTWs, we talk about the team and our interactions with the rest of the company. We adapt as quickly as our environment does.

And we keep the documentation moving too. The documentation, like the software, is not written once and then left to decay quietly. Instead, writing the perfect document is an iterative process:

  • Write the page, get it reviewed, and publish it as quickly as possible. There are people out there who need it now!
  • If you find a programming quirk while documenting the software, let the developer know.
  • When the developer changes the code, make sure the documentation is updated too.
  • Respond to comments from customers, developers, support staff and anyone else. Update the document immediately.
  • Monitor changes made by other people.

Past, present and future

Here’s my take on life, the universe and technical writing:

  • Ovid is 2000 years old but still rocks.
  • Long meetings and unwieldy email discussions are outdated.
  • Standups, RSS feeds and wiki watches are working right now — but they’ve been around a while already.
  • Tomorrow is an unknown, but it’s gotta be different.
  • Documentation will survive 🙂

Saving the best bit for last

I really like this bit of the Agile Manifesto:

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

It’s a paradox. (Another one, and what would we do without them.) As a technical writer, my aim is to reduce other people’s work, by making the documentation as simple and useful as possible. It takes a lot of work to achieve that simplicity. But it’s awesome because it’s what I love doing.

I guess that’s what’s behind the Agile Manifesto too.

Our team has picked up some great techniques over the last few months. This blog post is getting very long, so I’ll save them for my next post. Happy extreme tech writing!

Update: I’ve added some hints about techniques our team has learned in another post: The agile technical writer II

Update August 2009: Atlassian has just published a new section of its web site, called “agile@Atlassian”. There’s a section on how the technical writers do agile. There are videos too, including one of me (spooky). Go tech-writers@agile@Atlassian.

%d bloggers like this: