Draft reports

We’re conducting a code review of a client’s software platform. Although their work is mostly aimed at internal use within their own organization, they made the long term decision that Open Source is the right way to go, and release their code. This is awesome, and turns an otherwise bog standard consulting project helping a team of people improve their processes and practices into an awesome consulting project helping a team of GPL developers write even better software. Nice.

Last week we presented a draft of the report we’ll be submitting as a part of our engagement with them. After a series of meetings, my client asked if I would send him an electronic copy of the draft I had just presented to he could mark it up.

This caused a brief pause:

  1. ordinarily we would not release the digital form of a draft document;
  2. our work on this project has a partial audit aspect to it; they want us to review their practices and results to date. And one doesn’t normally submit draft audit reports to the people being audited!
  3. I had not yet had the opportunity to to make the (very large) number of changes based on feedback from our meetings with the client.

On the other hand:

  1. they’re the customer, they can have whatever they want;
  2. it’s not an audit;
  3. hell of a lot easier for our client to comment in-line rather than having to cut & paste stuff and/or describe it in an email before commenting;
  4. if the client can do some of the work fixing up terminology, etc, then by all means; indeed
  5. collaboration is good!

So, deep breath, why not. Record changes on, and send.

It struck me how all this aligned with the usual objections to Open Source. People don’t want to release anything before it’s perfect; the idea of outsiders (clients!) contributing to a the project’s “code” is utterly foreign. And yet. Contribution directly from the people you are working with means more targeted feedback; and people making things more like what they want to see through their own effort is the very essence of Free Software.

Icky icky blobs

Compared to source code, though, office documents are horrible. The change recording and acceptance functionality in OpenOffice Writer leaves a lot to be desired. Its “merge” capability (ie, trying to bring a document two authors have worked on the document in parallel back together again) is incredibly fragile; and if you’re not careful, it’ll decide that it won’t merge anything and will instead sit there and sulk. Better not to risk it. Which means you’re basically stuck having to send off the document and not work on it until you get it back again. Still though, “collaboration is good” (it helps if you keep telling yourself this).

This sort of thing makes me wish Open Document Format text documents were actually text, not binary. (Yes, yes, it’s a compressed zip archive of a bunch of XML documents, but the end result is still a binary blob). You can’t really apply the powerful software version control and external diff and merge techniques we live by in the distributed global Open Source communities to .odt files, which is a shame, because that would be multi-user document collaboration. I’ve speculated that storing an ODF document as uncompressed in a directory, rather than in .zip single file form might make it more amenable to version control, but there’s still the problem that the XML that OpenOffice spits out is … messy. Be interesting to have a tool that whose output was still valid ODF but which was more focused on keeping the XML super clean and human readable. If we had that, then the incredibly capable tools we have for managing parallel development of source code could facilitate collaboration on documents.

Meanwhile, time to put the finishing touches on this report. Back to work.

AfC