11

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.

3
  • 2
    I tagged this technical-writing because that's both my context and because I have the impression that this doesn't come up as much in other domains, but if anybody feels this should be more general, feel free to change that. Feb 8, 2012 at 20:19
  • If you ever found a solution to your problem I would like to know what it is. I'm dealing with similar problems and haven't found a perfect solution yet. I'm using Atlassian's Confluence and Jıra at my workplace but my project team consists of members who don't use the system actively so at the end I'm still updating everyone either via email or vocally :)
    – Montag451
    May 29, 2016 at 17:36
  • @Montag451 we ended up using the bug-tracking system (file a new bug for the other doc), but never felt it worked all that well. I've since moved to a new company and a larger team where the process instead is to fix everything that's affected even if it's not "your" doc (ownership is looser). I still feel like there should be some way to use source-control logs or Jira to do better, but maybe this is the best it gets. May 29, 2016 at 18:48

3 Answers 3

2

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.

6
  • Thanks. I apparently wasn't clear enough (sorry!). I'm not talking about a case where I make a change and I go and update all the affected places ("call sites"); I'm talking about the case where I make a change and that means co-authors need to go look at their parts to figure out what they need to do about it. Feb 8, 2012 at 21:16
  • @MonicaCellio: so you mean a project management tool, like Trello for example? See also: joelonsoftware.com/items/2012/01/06.html Feb 8, 2012 at 21:40
  • @MonicaCellio: The above solution still applies. You should look at github.com, for example. Version control is certainly not trivial to use, and there is a learning curve, but is the only real solution without storing the file in a central server and everyone having to edit the file from the same place. Feb 8, 2012 at 21:42
  • We're actually already using version control, but haven't found a way to use it to indicate "this changed so this other thing may need to be updated". Maybe the answer is a project-management tool; are any of those suitable for many small tasks? The ones I've seen (not many) seem to be tuned for coarser-grained tasks, like "implement this feature (3 weeks)". Feb 8, 2012 at 21:48
  • 1
    @MonicaCellio: Here is a link that might be useful reading: What are the advantages of using version control (git, CVS etc) in LaTeX documents. Even though that is a discussion related to TeX, the main principles still apply. I think version control along with a project management tool is what you need. Feb 9, 2012 at 16:16
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.

0

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.

1
  • 1
    Thank you. We're already using source control (Perforce). If I change code and miss a related change, that might be caught by the compiler, the unit tests, or the regression suite, so there's a safety net. If I change some documentation and miss another document that depends on that, nothing will catch that (before, maybe, the end user). The best approach we've been able to think of when "just fix it everywhere" doesn't work is "record it somewhere", but the devil is in the details, as they say. I'll check out Unfuddle.com; thanks. Feb 9, 2012 at 18:08

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge that you have read and understand our privacy policy and code of conduct.

Not the answer you're looking for? Browse other questions tagged or ask your own question.