Geek Answers Handbook

How do you write specifications together?

I work with a small team of (2 other) developers that are geographically distributed, and I'm looking for good ways to collaborate on specifications ... We think we can use Google Docs to write a spec, so that we can all have access to change its in a central place.

What did you do? What good ideas do you have?

+4
source share
7 answers

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

Compared to Google docs, you get:

  • Much Better Versioning and Tracking Changes (IMHO)
  • It’s much easier to start creating new documents for subsections.
  • Actual markup, not WYSIWYG (a matter of taste, I prefer LaTeX for Word).
  • Many other file types can be connected.
  • Very simple backup
  • It’s very easy to create a standalone version
  • You do not need to worry about storing sensitive materials elsewhere.

The disadvantage is that it is not WYSIWYG, which may or may not be a problem for you.

Of course, you can choose a Wiki implementation that supports the best editor, and possibly even a synchronous collaborator.

+2
source

Google Wave - exactly what it meant - collaboration

+2
source

IMHO , a word processor is the wrong tool for a programmer. The specification should be written in a text editor and use lightweight markup such as reStructuredText, AsciiDoc, etc.

The advantages of this approach are as follows:

  • There are excellent tools for managing plain text, which is already in the hands of programmers (VCS, automated build systems, diff, patch, program editors, grep, etc.).
  • Markup language allows you to express intention, not formatting.

This means that wikis seem like an obvious choice.

Personally, my whole tool chain:

+2
source

Choosing technology is one of the problems, and Google docs are a good choice IMHO. But the real problem is how to manage the process, for example. split tasks.

My suggestion is to first make sure that the platform and all related technologies are resolved - as much as possible. Then make a detailed table of contents. A well-designed TOC will allow you to properly distribute tasks, rather than “pacing” each other's work. Since then, you are each "flesh" of its designated sections, and also look at each other's work.

In fact, each sub-section of the TOC becomes an atomic unit of work that can be assigned and maintained by an individual who is also responsible for these sections.

Good luck

+1
source

I think it depends

  • How much do you write down specifications you all
  • If you are probably writing at the same time
  • Do you intend to publish specifications.

Google Docs is quick and easy to get started. It's also great that now you can export folders right away. However, for something to be published on the Internet, wikis or general cms are the best presentation vehicle. Wikis will also be integrated with your existing site.

If you have small specifications, primarily written by one person, then use any tool available where you post the project code or website. If you are unlikely to edit at the same time, then the wiki will be good.

I did a wiki thing, transferred documentation and a Google case.

  • The wiki value has a low initial force and lasts quite a while. At a certain size, it becomes pain.
  • The transmitted thing of the document (writes, e-mail, editing, e-mail, etc.) works only when one person starts everything. As soon as there are minor changes, it sucks.
  • The Google Docs case is great until you have several documents and several editors or want to publish it on the Internet.

Hth

+1
source

This is not programming related, but I personally used Google Docs to write shared documents and found it easy to use.

I would suggest enabling Google Gears, however, in case Google’s servers instantly disappear or your internet connection is unavailable.

0
source

For sharing specifications, you can try Gingko .

It is a map file editor, which means it is a combination between index cards and outliner, with real-time support and full Markdown support (as well as basic LaTeX).

We still lack several functions (version history, comments, etc.), but for some of the advantages of having everything in the tree structure, these shortcomings outweigh.

Writing specifications with this is great, because you can create a card for each user story and delve into it as much as you want (and sort them into categories if you want).

http://gingkoapp.com

0
source

More articles:


All Articles