How do you track dependencies for your co-authors?

Question

I and one or more co-authors, sometimes geographically distributed, are working on a set of related documents. Sometimes I will make a change in my part that affects someone else's part; this could be anything from changing a name to adding a new concept (that later parts should then use or reference) to changing the scenario for a running example. For large changes one hopes we'd all be talking about it first, but sometimes smaller changes come up that it's not worth calling a meeting about. How do you track those dependencies so you don't lose track of them?

Things we have tried include:

• Send email. Easy but can get lost.

• Have a central place to leave notes (shared document, wiki page, etc). This works pretty well if you can sort it by who/what is affected, so each person has just one place to look, but it can be kind of unwieldy if dependencies are vague or numerous.

• Use a bug-tracking system: works if everybody is using the same tools and the folks overseeing the bug database don't mind, but that's not always the case.

What are better ways to manage inter-connected work with co-authors?

Clarification: I'm talking about cases where I make a change and others will then have to make updates to their work, not about cases where I make all the relevant changes myself.

Answer 1

You can work together at the same document with tools like Google docs, but that maybe gets a little bit messy over time if you want to track all the changes.

To make the changes visible (I'm not sure if that's what you mean with "dependencies", but I guess so) my best bet is a source control system like programmers are using it. But to make use of its benefits, you should store your work in a comparable format.

What does that mean: Tools like Subversion or Git store your document in a (central) database. Everyone needs access to this database (the access is provided by the source control tools). If someone changes something, then the change is stored (tagged with his name) to the database/source control system. It also can be commented.

If the document format is human readable (like txt or xml), then a diff-program (which shows the differences between two files) can show the changes between the different versions of the file. I know that Subversion can also do this with the Word doc-format (which is a binary format, i.e. not human readable).

So the changes are directly visible. Additional information (why you made the change, for example) go into the comment.

Answer 2

In order of descending utility, IMO:

1. Project/feature/bug tracking software, for well-defined product changes. A must.

2. Email notification to other writers (broadcast) that refers to entries in #1 or to a wiki entry describing the doc change. The email summarizes the context & change enough that other writers can tell whether it affects them. The wiki entry provides details. Wiki tags provide organization/classification and facilitate search/lookup. Tags can include project names/numbers, bug numbers, and other thingies in #1.

3. Comments embedded in the doc can help point out details and locations of some doc changes. Source-control change logs can also help for this, but are coarse-grained.

#1 is preferable, when it can be used. Many doc changes reflect product changes, including bug fixes and new features. The doc changes for these can/should be managed together with the changes to the rest of the product (the doc is of course part of the product).

#2 supplements #1 - it is for anything that doesn't fit in #1 and doesn't need to be in the doc itself. But it is often possible for #2 to reference thingies in #1. An example of content for #2 might be a doc reorg - but even then it is often better to create a product project for the reorg, i.e., a doc project, and track it in #1.

#3 can help a writer who visits the result of your changes later. It can point out things that are not obvious and are specific to particular content - like good code comments.

Answer 3

Software developers deal with projects with millions of lines of code and collaborative writing projects deal with content on the order of thousands or hundreds of thousands of lines of text. I think the versioning approach used for software development is incredibly applicable to the writing process.

As a software developer I use versioning source control software (SVN, GIT, etc) to track changes between a large set of code across multiple developers. I've started writing a book (solo) and I've tackled the problem of managing thousands of lines of narrative using the same technique.

I am writing my manuscript in a glorified text editor (Notepad++) and this solution many only be applicable to this kind of approach (Word docs will be messy, in other words).

I use Unfuddle.com which has an "Issue tracking" thing that may be useful for communicated between collaborators.

I think the most important component is to have contributors consistently provide a reference number to an "Issue" when they are saving their changes. This way when you look at the issue you are dealing with, you can see all the related changes throughout your document.

There may be a learning curve for contributors to adopt some technical skills, but depending on the size of the project I think it would pay off in the ease of managing the work.