I’ve been having a wonderful time dealing with open source software recently. OK I’m lying – it’s been horrible. I even know what I’m doing, having brought a number of open source components in-house for use in the products we sell. But sometimes things go awry in spite of your experience level. I won’t say who’s involved because it’s not really their fault – just a limitation in the structure of the information they publish to the rest of the world. And since this blog is about information structures, let’s talk about it.
There is a process that every company should go through when acquiring open source software for internal use or to include as part of the products or services that they sell. The stakeholders in the process are:
- Management – to assess risk and potential reward and long-term project viability;
- Technical – to assess feasibility, estimate integration and customization costs, and long-term project viability; and
- Legal – to assess liability risk, ownership and licensing issues.
All stakeholders must sign off on the adoption of the component before you can proceed with it. But unfortunately the process is not linear – you don’t progress from stage 1 technical feasiliby to stage 2 management assessment to stage 3 legal sign-off. Instead, the process goes through multiple stages for each stakeholder, with a couple of “synch points” where they all get together and agree to continue or not.
I don’t know whether this process has an analogue in a non-software environment. To be sure, there are numerous “free” licensing models that have their own idiosyncratic requirements and hence a need for Legal to get involved, but software analysis is much deeper because software is abstract and complicated. For example, let’s say you want to use a photograph from flickr on your commercial website or as part of a product. Starting from the creative commons page, you follow the non-commercial license links and find a suitable photograph, then you probably need to make sure your Legal department is fine with using the photograph and the business side agrees with the use of the photograph. Most of the steps are technical and artistic, really. Once Legal and management agree on a few examples, they can mostly rubber-stamp future proposals.
Anyway, to my situation. I am responsible for the technical analysis. After reading through the available online literature, and searching through community postings, it seemed that the component satisfied one of my requirement, which was conformance to a particular standard. Unfortunately, we needed two versions of the component – the most recent one, to ship with the next release of our product, and an older version to ship with the previous release of our product. And that was the problem. None of the available literature indicated that the older component would not satisfy the requirements, but then again none of the available literature indicated that the older component actually did satisfy the requirements. This is partly because at a certain point in time the component authors updated the specifications page to indicate that the component conformed to the specification, but I had no idea when that change was made. Also, the specification was relatively new so nobody was really asking about conformance when the earlier version of the component was published.
This is a big problem in open-source projects. The authors don’t want to get bogged down in retroactive work. They don’t want to establish conformance to a standard on a version of the component that was published long ago. They don’t have a business motivation to maintain old code – heck, they’re giving it away for free! Why are they giving it away for free? In part because they can write on their resumes that they’ve been involved with leading-edge technologies and current standards. So bringing an old version of the component up to a standard with which they are already familiar (and which is already on their resume) is frankly a waste of time. And users like me, who certainly can contribute their code fixes back to the community, are not necessarily project “committers” (one of the folks who gets to check in code) so it’s a bit of a hassle to get your changes in. I’ll do it – Legal tells me it is required – but it’s a cost I hadn’t anticipated.
So here’s the issue: Had I known that the old version of the component did not conform to the standard, I would have revised my work estimates upwards – significantly. It takes a long time to get up to speed on some of these open-source projects. They are complicated and have multiple dependences on other open-source components, which themselves are constantly evolving. The best resolution to the problem is to maintain a separate documentation stream for each version of the component.This is how it might work:
- A user writes to the community pages and reports a defect (let’s call it Defect A) in version 2.1.3 of the product
- The defect is fixed and the relevant code changes are linked to the defect report
- Another user encounters a defect (Defect B) in version 2.0.1 and does a search on the community
- The defect seems to be a match for Defect A
- The user rebuilds version 2.0.1 with the changes introduced for Defect A and it works
- The user links Defect B to Defect A
- A third user encounters a similar defect (Defect C) in version 2.0.5 and does a search on the community
- Since version 2.0.5 comes between the two previous versions, automatically the changes in Defect A are proposed as the appropriate resolution of the product
And so on. There is a large number of scenarios around this, including scenarios where the defect is officially fixed in a subsequent version of the component, or scenarios where the defect is no longer relevant in future (or prior) releases of the component. In an ideal world,
- the defect tracking system is traced to the changes that fix the defect;
- the community postings are tagged by the versions of the component to which they apply, and to which they might apply;
- the component authors carefully update the information to indicate the versions to which the defect can never apply, or should never apply; and
- the search engine guides the user to the right results when the component version matters; and
- the user interface helps guide the user to the right results by presenting just enough information to help the user decide quickly whether the hit is relevant.
That’s a lot of moving parts, but typical of issues that arise in information architecture. It’s not just about the architecture. It’s about tools, people, and business motivation too.