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?

@Yuval: why not? You need specs for programming projects, right? Notice that it doesn’t say “not programming”, it says “not programming *related*”. — Konrad Rudolph, Nov 04 '09 at 16:33
Saying that a discussion about specs is not related to programming is like saying that blueprints have nothing to do with the construction of a building. — Paul Sasik, Nov 04 '09 at 16:42
I agree with Konrad. Writing specs seems like a perfectly programming related topic to me. — Simon P Stevens, Nov 04 '09 at 16:45
I'm voting to close this question as off-topic because it's a workplace issue, not a programming question. — EJoshuaS - Stand with Ukraine, Nov 29 '18 at 03:55

score 2 · Answer 1 · answered Nov 04 '09 at 16:39

2

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

answered Nov 04 '09 at 16:39

AdaTheDev

142,592
28
206
200

I thought about adding that, as well. Unfortunately it’s still not very mature and the lack of an “undo” feature (notwithstanding the technical difficulties of implementing it) does some serious harm. – Konrad Rudolph Nov 04 '09 at 16:55
It is my uninformed opinion, that Google Wave increases the ease of content generation, but at the expense of consuming that content. A wave can quickly devolve into a convoluted spaghetti of blips. If judging by our experience with e-mail, we need to have less (more focused) information, not more information. That said, for the task at hand, and certainly for creating a working draft, Google Wave might become a strong candidate. – Chen Levy Nov 04 '09 at 17:16

score 2 · Answer 2 · edited May 23 '17 at 12:30

2

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

edited May 23 '17 at 12:30

Community

1
1

answered Nov 04 '09 at 16:43

Chen Levy

15,438
17
74
92

Markdown is suspiciously absent from your list. – Konrad Rudolph Nov 04 '09 at 16:55
Markdown is nice for what it is. It is simple and readable, but also a bit too limited for a spec. – Chen Levy Nov 04 '09 at 17:04
Okay, what can RST do that Markdown can’t do? As far as I know, nothing. Notice that there’s also Markdown Extra which can do even more than either Markdown or RST, as far as I know. Furthermore, Markdown basically includes all of HTML. So in summary, I think that RST cannot do anything that Markdown Extra can’t also do (notice: unlike Markdown, it has *tables*). – Konrad Rudolph Nov 04 '09 at 22:04
If you need to resort to HTML tags, you lose. It make your markup tied to HTML. Personally, I like HTML, but it might not be appropriate in some cases. As a markup that designed to represent HTML, it is concerned with form (emphasis, strong emphasis, etc) rather then function (term definition, abstract, notice, warning, author, etc). Admittedly I did not dive into Markdown Extra, so I might miss some critical information here. That said, I did not rule out Markdown, and did not mentioned some other lightweight markups such as Wikitext, but the `lightweight markup` link above list all of them. – Chen Levy Nov 05 '09 at 07:11

score 2 · Accepted Answer · answered Nov 04 '09 at 18:44

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:

Much better versioning and change tracking (IMHO)
Much easier to start new documents for subsections
An actual markup rather than WYSIWYG (a matter of taste, I prefer LaTeX to Word).
Possible to attach variety of other file types
Very easy to backup
Very easy to create an offline version
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.

Google documents are also very easy to backup and to create an offline version (File->Save as). — Petr Hudeček, Apr 15 '17 at 14:33

Paul Sasik · Answer 4 · 2009-11-04T16:44:00.267

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!

The division of labor/responsibility is a great point. See my answer re:using http://gingkoapp.com , as it turns your whole document into a TOC-like tree structure, with cards of text as atomic units. Great for divide and conquer. — AdrianoFerrari, Jun 26 '14 at 10:14

score 1 · Answer 5 · answered Nov 05 '09 at 01:22

I think it depends on

How heavily into writing the specs you all are
If you're likely writing at the same time
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

score 0 · Answer 6 · answered Nov 04 '09 at 16:32

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.

score 0 · Answer 7 · answered Jun 25 '14 at 09:53

For writing specs collaboratively, you could try Gingko.

It's a card-tree editor, which means it's a mix between index cards and an outliner, with real-time collaboration and full Markdown support (as well as basic LaTeX).

We are still missing several features (version history, comments, etc), but for some the benefits of having everything in a tree structure outweigh these drawbacks.

Writing specs with it is great, because you can create a card for each user story, and drill into it as much as you like (and organize them into categories if you'd like).

http://gingkoapp.com

How do you collaboratively write specs?

7 Answers7