Getting Started with Subversion–Part 3.3:Communication and Logs

After reading the previous article, you may have the impression that I think collaborative writing is a bad thing. Nothing, however, could be further from the truth. When you write with others:

• it’s possible to distribute tasks according to individual strengths, meaning that the finished product will (probably) be more than a sum of the parts
• brainstorming is more effective, more people means more ideas
• not only will you have more ideas, but as you discuss, challenge, and research the topic amongst the group, you will have different ideas than you might develop on your own
• having many people working on a project gives it energy and focus, which is tremendously helpful upon entering the hinterland of any project commonly known as “middle”

Collaboration is good, but it is also complicated. It takes a great deal of work for a collaborative project to be success. You have to balance competing needs against one another. On the one hand, it is really important to provide an author the freedom and space required to own her ideas. At the same time, though, you need to make sure that everyone is clearly communicating about the project and where it is headed.

Making sure that everyone is on the same page and that efforts are coordinated is a complex challenge. It requires meaningful discussion happens; establishing a system for sharing documents and knowledge; and that goals, scope, audience, and purpose of the project are well defined. In many ways it shares much in common with another complex endeavor, coordinating the care of a medical patient.

Communication Challenges

Helping a single patient get the care needed to treat a disease is difficult. For any one procedure or treatment, there are dozens of people involved – nurses, technicians, pharmacists, and support staff – and these people are in addition to the doctor who proscribed it. For the treatment to happen, the whole team needs to to know what’s happening and what their role will be. They need to briefed on relevant test results and potential complications. This is a big job.

In general, the healthcare professions do a terrible job of sharing this information with one another (at least in the United States). You can see the symptoms of the problem every time you go to the doctor’s office or hospital: patients filling out the same forms multiple times during a single visit, answering the same questions to every provider that walks through the door, and repeating the same stories to a dozen different people. But though communication in healthcare is a shambles, it offers some instructive lessons. To explore these further, let’s consider a relatively simple example: a primary care doctor sends a patient to a specialist for an expert opinion.

To have a good outcome, where the patient learns what is wrong with him and the referring physician learns what she should do about it, three things need to happen:

1. An appointment with the specialist needs to be scheduled and a copy of the patient’s existing history and the notes must be sent for evaluation.
2. The patient should be seen and evaluated. Specialty diagnostic tests may be ordered.
3. The specialist will determine a diagnosis and communicate all of this back to the referring doctor, along with a copy of his notes, test results, and a plan of care.

Though this might seem pretty easy, this simple chain of events rarely happens,¹ consider the results form a study ² published in January of this year. When asked in a survey about how often they pass along important documentation, 69% of primary care physicians always or mostly pass on a patient’s history and reason for a consultation a specialist. Fewer than 35% of specialists, however, report receiving them. The same thing happens in reverse: 81% of specialists said that they send consult results back to the referring primary-care doctor, but only 62% of primary-care doctors say that they receive the information.

Think about what this means for a minute. We are talking about information that doctors not only should be sending to one another, but that is often mandated by law. Before making a diagnosis, a specialist needs to know the full medical history and the impressions of the other physicians taking care of the patient. This is not always material that can be obtained from the patient directly, it’s stuff required to do the job. Yet, the specialists receive it less than half the time. The same breakdown in communication then happens in reverse with the same implications to the patient’s life and health.

Even if the communication happens, doesn’t mean that it’s effective. Sending stacks of papers and notes is tremendously inefficient. A chart contains a great deal of important data, but not everything a doctor notices gets written down. Busy specialists may choose to skim the notes and comments, missing a vital piece of evidence. It would be much better if one doctor would call the other and briefly talk about the plan of care. This verbal communication might then be supplemented with what’s available in the notes. Yet, from my own personal experience – after nearly a decade of working in hospitals and around doctors – has been that this almost never happens.³ As a result, essential information – data that can save a life or result in death, such as whether a patient is allergic to a drug – is simply left unsaid, and mistakes occur,hundreds of thousands of them each year.

Lessons for Writers

Collaborative writing, like medical care, needs to be coordinated. Writers require more than just than the text of a manuscript to be effective. Like doctors, they have to talk to one another. They should meet, find ways to share documents and knowledge, and ensure that everyone remains on the same page. Doing these three simple things will go a long way to ensuring that as you write, your collaboration will be effective and fruitful.

Now for some bad news: for the first challenge, there isn’t much that Subversion can do to help you. At the end of the day, successful communication starts and ends with a group commitment, you just have to work at it.

SVN, though, can help with the latter two challenges: by making sure that everyone in the project has access to all of the files (working drafts, reference documents, citation libraries, etc.), and that you have a centralized location to provide updates on how the work is proceeding. In fact, it’s a brilliant way to address both.

This is because the features which enable effective collaboration are the same that allow you to synchronize your work amongst multiple computers and provide a log for the history of your changes.⁴ When working with others, though, the secret lies in how you use them. Below, you’ll find two suggestions for getting the most out of them.

Suggestion 1: Structure Your Files

You already know that Subversion can be used to synchronize nearly any type of file to everyone else working on the project. Here is where you need to put that feature to good use. In addition to the drafts of the manuscript and images, it’s also a good idea to add other assets to the repository. These might include specification documents, articles, or other material which everyone will need access to.

If working on an academic manuscript or a piece of non-fiction, it’s especially important to add reference databases. Using the reference databases that others have created can save you an enormous amount of time, especially as you don’t have to go out and look up the citations on your own. Different groups each have their own way for managing reference databases, but my experience has been that it’s better if each user keeps their own as a distinct file. In programs such as LyX, it’s easy to check for and remove duplicate references (which someone should probably do at a semi-regular interval). Other groups, though, prefer to use systems as Zotero and share their reference databases that way.

Whichever system you choose, make sure that the files are structured in a consistent manner. Reference documents and schematics might be added to a “References” folder, databases to a “Bibliography” folder, images or schematics to an “Images” folder, and so on. Ensure that everyone knows where to find important documents in the repository. When adding new material, explain it fully as part of comment in the log.

Suggestion 2: Centralize Communication Using the SVN Log

Which brings me to the second recommendation: other than long, meaningful discussion – which is best accompanied by food and drink – try and communicate using the SVN log. When you commit a change, leave a message. When you add a reference file, add an explanation. When updating your reference database, explain what’s new and why it’s there. If you’d like for another author to look at a file, let her know as part of your commit.

Image may be NSFW.
Clik here to view.

The SVN log is a powerful tool that can be used to coordinate and communicate the status and direction. When making changes, use it to explain those changes completely.

Short messages can communicate a great deal about what’s changed in a project and what still needs to change. It gets everyone on the same page and provides a place for coordinating work and starting longer conversations. And because it’s all in one place, you can always tell people to “Look at the log” in order to get up to speed.

There is also a wonderful side benefit to using the SVN log. When you consistently use good comments when committing changes, adding resources, and locking files, the repository contains not only every change you have ever made, but also contains an explanation of why those changes happened. Such records are invaluable as you forget things later on.

Summary

Effective collaboration is about meaningful communication. Subversion makes it easy to structure and send relevant assets and reference material for a particular project, you simply add it alongside the drafts and other material. This makes sure that everyone has access to the files needed for their part of the work. Through the use of the SVN log, you can coordinate your efforts and keep everyone abreast of where things are headed. This helps to keep everyone on the same page and informed, and that’s 80% of the battle.

In the next entry in this series, we’ll look at one final way that Subversion can streamline group work: making it possible to create snapshots of a project for review using branches.

__________________________

Notes

1. Physician to physician communication is something of a joke in the medical profession. It mostly doesn’t happen. As close as they usually get is encouraging one another to read the patient’s chart.
2. Ann S. O’Malley and James D. Reschovsky, “Referral and Consultation Communication Between Primary Care and Specialist Physicians: Finding Common Ground,” Arch Intern Med 171, no. 1 (January 10, 2011): 56-65.
3. After searching PubMed and other biomedical databases, I was unable to find quantitative studies looking at how often doctors speak to one another. Typically, the communication takes place through a nurse or other technician who receives an order for a consult and then relays it to the specialist physician.
4. For more information about how to create repositories, add files, and synchronize them between computers, see Part 1 of this series.

Getting Started with Subversion–Part 3.3:
Communication and Logs is a post from: Apolitically Incorrect. Copyright 2009 – 2010, Rob Oakes.