How do you track dependencies for your co-authors?
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.
4 answers
You are accessing this answer with a direct link, so it's being shown above all other answers regardless of its score. You can return to the normal view.
In order of descending utility, IMO:
Project/feature/bug tracking software, for well-defined product changes. A must.
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.
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.
This post was sourced from https://writers.stackexchange.com/a/12271. It is licensed under CC BY-SA 3.0.
0 comment threads
I've changed teams (and companies) since asking this question years ago, and the doc set is even larger on my current team. Here's how we manage changes that affect parts of the documentation with different primary/responsible writers.
First, we do use source control as mentioned in another answer. At my insistence, we now do work on branches and merge to master only when work is complete.
Because we use branches, more than one writer can work on the same branch at the same time. If my change has impact on someone else's area, we can both work on it together without making master inconsistent.
That said, we try to be flexible about boundaries. If I can make (or propose) a change in someone else's area, I should do so and then ask the primary author to review it. That's easier to coordinate than working together on the branch when we can't just sit down together. (Yeah, my current team is geographically distributed, too.)
And when all else fails -- for example, when the other affected documentation is a blog post or a training module, neither of which is part of our doc repo -- then we file tickets in our bug-tracking system to make sure things don't get lost. We tie all non-trivial work to tickets already, and can use dependencies in the ticketing system to tie tasks together. Applying some discipline to tickets (it's not resolved until everything's on master) helps to prevent things from falling through the cracks.
We do have informal communication channels -- chat, email, team meetings, and the like. These can be extremely helpful when I mostly understand what I need to do in someone else's area but have a few questions, for instance. Sometimes the result is an explanation and sometimes the result is that the other writer does that part of the work.
0 comment threads
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.
This post was sourced from https://writers.stackexchange.com/a/5000. It is licensed under CC BY-SA 3.0.
0 comment threads
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.
This post was sourced from https://writers.stackexchange.com/a/4977. It is licensed under CC BY-SA 3.0.
0 comment threads
0 comment threads