Writing user documentation collaboratively in an Agile environment

Hi,

You provide wonderful newsletters full of useful information. Thank you.

I’m a Senior Technical Writer in a small company, and I have one contractor working for me. We have come up against a challenge. <snip>… My team currently uses RoboHelp, which is not a collaborative, team tool for writing. The company likes to think the product addresses this issue, but they really do not.

I have searched for a writer-friendly product that allows collaborative, team writing on a project. Unfortunately, I haven’t found anything. What product do you recommend for teams working on projects together? Right now we have to share files, meaning only one of us can work on the project at any given time. This is a serious issue for us since we are in an Agile development environment where we support twelve developers. More will be added soon, but we there are no plans to bring on more writers.

TS

How would you advise TS?

6 Comments

Colum McAndrew

I’d take issue that Robohelp is a tool that does not allow collaboration between team members. As the senior member of a team of five writers using RoboHelp I can testify that it is.

Obviously some form of source control solution is required. RoboHelp actually comes with its own source control application (called RoboSourceControl) that can be used. Other source control applications that work very well with RoboHelp are Microsoft’s Team Foundation Server and the Tortoise SVN. We use the later very effectively.

Another consideration is how your project source files are structured. In a team environment project structure should consider the likelihood of who is likely to be updating different parts just as much as whether a chunk of the help project fits in one logical place.

mick davidson

TS, do you want to use the system to produce Help files only, or other documentation as well?
As for your writer:developer ratio – you’re doing very well – I am a lone writer supporting a good 20 developers, plus the support and consultant depts (plus the two companies we bought last year, neither of whom is populated by native English speakers, yet all our docs are in English). 🙂 There’s not even the smell of part time help wafting my way! 🙂

Anne Gentle

Hi TS – Many writers have gone through the same shift as you. I think you’ll find you either have to embed the docs with the code or find a wiki/web-based CMS that can deliver the output your customers expect.

I’ve blogged a bit about Agile and tech comm – some of my favorite articles include:
http://justwriteclick.com/2010/01/26/collaboration-thoughts/

http://justwriteclick.com/2009/11/30/collaborative-authoring/

http://justwriteclick.com/2009/09/10/advanced-wiki-techniques-collaboration-in-authoring/

I like Confluence and Mindtouch myself. Do a good old-fashioned requirements collection and ensure you serve users first, devs second. 🙂

Dee Elling

I’ll add say that the 10+ regular writer/contributors to our MediaWiki are much less frustrated with the tooling than my 2 writers using RoboHelp. Just as a somewhat subjective data point.

It’s pretty easy to get help out of MediaWiki, but not PDF. I agree with Ann, MindTouch and Confluence are the best wikis for most writing projects.
-Dee

-Dee

Bob Propes

Hi Virginia,

After 20+ years inthis business, my advice would be don’t let your team get out-smarted by technology. The simplest answer is right in front of you. Adobe Acrobat. It has great mark tools and super change tracking functionality. My approach to projects is simple. 1. Keep the number of collaborators to the smallest number possible. 2. All reviewers need to keep in mind that this is a document in time. Not one of the pyramids. Its not going to last forever. And 3. Put a clock on it. Let’s face it, writing is about revision. But if you have no finish line, it becomes a living document that is never finished.

Hope that helps!

Bob Propes

Jon

I know this is a pretty simple solution, but a shared folder in Google Docs could be very effective. In the world of cloud computing, creating shared documentation is key. A wiki might also be an effective way to go about it.

Leave a Reply

This site uses Akismet to reduce spam. Learn how your comment data is processed.