Comments on: The agile technical writer II

By: Social Media Marketing Playbook - book review « just write click

Social Media Marketing Playbook - book review « just write click — Tue, 18 Mar 2008 15:04:20 +0000

[...] agree whole heartedly. I think the Agile technical writer that Sarah Maddox describes is precisely the right person to be identifying keywords, get RSS watch lists configured, and read, [...]

By: one man writes » Recently Read

one man writes » Recently Read — Mon, 03 Mar 2008 11:51:27 +0000

[...] The agile technical writer An excellent write up of the typical processes followed by a technical writing team in an Agile environment. It’s good to read this kind of thing, as it matches roughly what we do so… we must be doing it right? [...]

By: Tom Johnson

Tom Johnson — Thu, 21 Feb 2008 20:39:37 +0000

Thanks for your response. I didn’t realize that JIRA was an Atlassian product until just the other day. I’d seen the RSS capabilities, but hadn’t used them because, based on my experience with SharePoint 2007, I thought the feeds would be problematic in an authenticated, firewalled environment (esp. using a feedreader like Google Reader).

But yesterday I downloaded Feedreader and added feeds for the projects I’m on — wow. This is exactly what I’ve been missing in my attempt to stay in the loop of what’s going on in development. The tool is robust, but the feeds make it manageable.Thanks so much for the idea.

By: ffeathers

ffeathers — Wed, 20 Feb 2008 21:08:09 +0000

Hallo Tom

No worries about the fish and chips thing I’ve lived in England for a while. And I wasn’t born in Australia, though I have recently become comfortable with saying ‘no worries’!

We do write all our documentation in Confluence — well, except for the JIRA docs, which are in Apache Forrest at the moment but planned to convert ASAP. Confluence allows you to export a space (sort of a wiki within a wiki) to PDF format, which is handy for printing and offline use. You can also export a space to HTML and Confluence-specific XML. And you can export a page to PDF or Word format.

Yeah, keeping things simple is complicated We use things like information-chunking — breaking subject-matter into small, logical chunks with highlights and headings to help people find their way. And we divide the material by audience e.g. a user guide and an administrator’s guide — so that we don’t tell people things they don’t need to know. And we try to de-obfuscate the developers’ language.

Hey, sounds like you’re a JIRA junky too. Yes, we use JIRA to keep track of what the devs are doing. We also attend the standups, and just generally keep all our antennae quivering.

Nice to get your comment!

By: Tom Johnson

Tom Johnson — Wed, 20 Feb 2008 05:26:54 +0000

Now I feel dumb. I just looked at your About Me page and see that you’re Australian, not English. Sorry about the fish and chips comment. I’ve never been to Sydney, but it must be a beautiful place.

By: Tom Johnson

Tom Johnson — Wed, 20 Feb 2008 05:22:39 +0000

I really enjoyed this post as well as part 1. So do you write all your documentation in the Atlassian Confluence wiki? If so, what do you do when someone asks you for a printout of everything in a manual format?

I also liked your comments about simplicity. In a product that is fairly sophisticated, what techniques do you use to keep it simple?

The whole paragraph on tidbits versus titbits was funny. I’ve been to England before (love the fish and chips with lemon juice), but I never heard anyone say titbits.

Do you use some kind of tracking tool like JIRA to keep track of what developers are coding and fixing?

By: Gordon

Gordon — Sat, 26 Jan 2008 10:57:24 +0000

Yeah that’s pretty much what we do as well. Another tip is to seat the tech writers with the development teams they are working with. Wouldn’t work in your place though.

Our teams rotate members after every release, and the tech writers do the same. You learn a lot of info from the conversations they have, and it means that we attend all the meetings, from the very first design.

The most daunting bit for me was the ‘iterative development’ bit, which I’ve called “trickling” the information as and when it is available and concrete enough to be used (more on that on my blog).