Monthly Archives: January 2008

Heart of documentation

Documentation answers all the big questions of life: How did I get here? What’s it all about? How do I do it? What’s next?

This leads to the inescapable conclusion that documentation is at the centre of the life, the universe and everything.

Even if all it says is: ‘Wrong way — go back’.


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.

Do wikis save trees?

Do wikis save trees, and do we even want to save trees? Global warming, carbon-trading, green politics — where do wikis fit in, and are they even relevant?

I’ve worked in an office environment for quite a few years. Recently, I’ve started using a wiki to write, review, update and read documents and to share ideas. My desk is definitely more paper-free than ever before, largely due to the use of the wiki.

So my gut-feeling is to say, ‘Hey, wikis save trees!’ Being a tree-hugger and a wiki-hugger both, this feels like a good place to be.

But take a look at this article by Chris Anderson, which seems to prove that my good place is an illusion. Printed documents have a lower carbon footprint than online documents! So even if wikis save trees (which is debatable in itself) perhaps we don’t want to save trees. The paper industry puts them back in the ground, whereas a wiki doesn’t.

Chris Anderson’s article has a very long, heated and interesting comment trail. After reading it, I’d like to take a slightly different tack. He is concentrating on articles which are written once, and then read by many people. Websites are viewer-intensive.

How is a wiki different to a web page?

Many wikis are used for short-term collaboration rather than, or as well as, longer-term information storage. You might put an idea up on a wiki. A number of people would then review it, add their comments, and update the page. At the end of the process, an idea has been formed and is out there in the noosphere. People probably won’t go back to the wiki often to look at that particular idea. You could say the wiki is scribble-intensive.
The key thing is: In the review and refinement process, if we use a wiki then we aren’t passing around and scribbling on pieces of paper. We aren’t even exchanging long and confusing email chains which eventually force you to print them out just to keep track of who said what in reply to whom. Nor are we using Word documents, where the change-tracking is just as confusing :mrgreen: Nor even any backs of envelopes or matchboxes.

Instead, the wiki page distills and merges all updates so that it shows the latest aggregation at any one time. And if you need to, you can go back and examine the change history to see who did what.

We’re online anyway. Given that the bad effects of the technology exist whether you use a wiki or some other form of website or computer technology, perhaps wikis are a step in the right direction.

What do you think?

Does anyone have any figures which go to prove this question either way? Maybe someone in the publishing industry has some experience of using a wiki for pre-publication drafting and review. Or perhaps there are some other industry-specific stories out there. Do you have anecdotal evidence, or even some documented statistics?

Ozzie tree shedding its bark

Here’s a tree in our garden. In early summer (that’s December on this side of the world, when I took this picture) the tree chucks all its bark on the ground. The new ‘skin’ underneath is a lovely mixture of salmon pinks, oranges and greys.

The story goes that early visitors to Australia were amazed by trees like this, because they shed their bark in summer rather than their leaves in winter.

Do wikis save trees?

Sydney Red Gum (Angophora costata) aka smooth-barked apple.

Wiki makeover

J the TW writes on Spacebar about some wiki restructuring that she is about to undertake. Her blog post struck a strong chord with me, and probably will with a number of other wiki-huggers out there. When a wiki gets to be of a certain age, it needs some work done. In some cases, it may even need an extreme makeover. Who else has a story to tell? And should you even try to put structure in a wiki?

My wiki makeover story

Like J, I have just passed the 6-month mark at my new job. Writing in and managing a wiki is a large part of what I do. One of ‘my’ wikis needs some body sculpting. It’s been around quite a few years now, and parts of it are looking a bit tired. I’m thinking a face lift, a fair bit of liposuction, plus definitely some implants and enhancements.

The wiki in question houses the technical documentation for the Confluence software product. Yes, it’s a wiki which documents a wiki. It’s the oldest of our product documentation wiki spaces, and is updated continuously by a large number of people. It has kind of grown organically, to match the needs of a fast-growing company plus a rapidly-expanding software product. The wiki pages are updated by technical writers, support engineers, developers, sales staff and anyone else within the company who sees something that needs doing. In addition, anyone in the whole wide world can add comments to the wiki pages. These comments often contain useful information, which should ideally be incorporated into the pages at some time.

Enter the technical writer. It’s definitely within my portfolio and skill set to re-organise the documents, excise the out-of-date pages, add missing bits and sort out the structure.

Two hiccups are immediately obvious:

  • Time: It’s hard to fit in a large maintenance task like this, especially when there are new features rapidly and continuously appearing and demanding to be documented.
  • Sustainability: With so many different authors, the wiki will tend to revert to its current muddle soon after the restructuring task is done. (Is it ever done?) That’s entropy, man.

Should you even try to structure a wiki?

It’s a good question. It’s even a philosophical question. Isn’t a wiki meant to be an amorphous collection of pages which the reader can surf via a search engine, an index, RSS feeds and page-watches to catch the latest updates, or even just via the lucky-dip technique? Isn’t a wiki kind of like a mind map, with free-thinking links darting here, there and everywhere? You could compare a wiki to the nutrient soup which purportedly gave rise to sentient life. A wiki enthusiast might justifiably believe that we should not impose a hierarchical structure on the wiki gloop.

Well, my answer would be: ‘Yes’, wikis make excellent nutrient soup which allows ideas to bubble up to the surface and be scooped up by a passing RSS feed. But ‘Yes’, you can also add structure to allow human readers to browse in a more methodical way when that suits them. To some extent, it depends on the purpose of the wiki concerned. When the wiki contains technical and support documentation, structure is a plus.

Some examples of structure might be:

  • A table of contents.
  • Division of documents by audience.
  • Page hierarchies, so that you can group pages which deal with the same topic.
  • Headings within pages.
  • Similar look and feel across the pages which deal with the same subject.
  • And so on – your typical tech writer stuff.

We have some other wiki spaces with good structure. Here’s an example.

Quelling the hiccups

If your structure has some logic to it and is readily visible, then other people will tend to follow it rather than add to a spaghetti-bowl of documents. Our brains are wired to recognise patterns, and we usually like contributing to the symmetry rather than breaking it. Technical writers are trained to chunk information and to present it in ways which appeal to other humans. So all we have to do is to apply these techniques to a wiki. That takes care of the ‘sustainability‘ hiccup. Easy πŸ˜‰

The ‘time‘ problem is less easily solved…

Watch this space

I’m planning to get to work on the Confluence wiki. Probably the best thing is to tackle it in manageable pieces. I have a few tasks mapped out already. Let’s see how it goes! If J the TW beats me to it, I’d love to hear her story!

%d bloggers like this: