How do you collaboratively write specs?

Question

I am working with a small team (2 others) of developers that are geographically dispersed, and I'm looking for good ways for us to collaborate on specs... We're thinking we might use Google Docs to write the spec in so we can all have access to modify it in a central location.

What have you done? What good ideas do you have?

Answer 1

This isn't programming related, but I've personally used Google Docs to write shared documents and found it easy to use.

I would suggest enabling Google Gears however, in the event that the Google servers go down momentarily or an internet connection isn't available.

Answer 2

The choice of technology is one issue and Google docs is a good choice IMHO. But the real challenge is how to manage the process e.g. divide the tasks.

My suggestion is to first make sure that the platform and all related technologies are decided-upon as best as feasible. Then, compose a a thorough table of contents. A well-designed TOC will allow you to divide tasks properly and not "step" on each others' work. From then on you each "flesh" out your assigned sections as well as review each others' work.

In effect, each TOC subsection becomes an atomic unit of work that can be assigned and maintained by an individual who is also accountable for said section(s).

Good luck!

Answer 3

Google Wave - exactly what it's meant for - collaboration

Answer 4

IMHO, a word processor is the wrong tool for a programmer. A spec should be written in a plain text editor, and utilize lightweight markup such as reStructuredText, AsciiDoc etc.

The benefits of such an approach are:

• There are excellent tools to manage plain text, that are already in the hands of programmers (VCS, automated build systems, diff, patch, programming editors, grep, etc.)
• A markup language allow for expressing intent rather then formatting.

That in mind, a Wiki seem to be the obvious choice.

Personally my tool chain of choice is:

• reStructuredText as the markup language.
• Trac as a Wiki
• Firefox + the it's all text extension
• Emacs + rst-mode

Answer 5

If you have an intranet or VPN, I would actually consider installing and using a small Wiki for these specs.

Compared to Google docs you get:

1. Much better versioning and change tracking (IMHO)
2. Much easier to start new documents for subsections
3. An actual markup rather than WYSIWYG (a matter of taste, I prefer LaTeX to Word).
4. Possible to attach variety of other file types
5. Very easy to backup
6. Very easy to create an offline version
7. You don't have to worry about storing sensitive materials elsewhere.

The disadvantage is that it is not WYSIWYG, which may or may not be an issue to you.

Of course, you can pick a Wiki implementation that supports a better editor, and possibly even a synchronous collaboration one.

Answer 6

I think it depends on

1. How heavily into writing the specs you all are
2. If you're likely writing at the same time
3. Whether you intend to publish the specs.

Google Docs is nice and easy to get started with. It's also great that you can now export folders all at once. Still, for something that's going to be published to the web, a wiki or general cms is a better presentation vehicle. A wiki will also integrate with your existing site.

If you've got small specs, primarily written by one person then use whatever tool is available where you're hosting the project code or website. If you're not likely to be editing at the same time then a wiki is good.

I've done the wiki thing, the passed document thing and the Google Docs thing.

• The wiki thing has a low starting effort and lasts a pretty long time. At a certain size it does get to be a pain.
• The passed document thing (writes, email, edit, email, etc) only works while one person is starting everything up. As soon as there are even minor edits then it sucks.
• The Google Docs thing is fine until you have several docs and several editors or want to publish it online.

hth