October 8, 2010

Commercial Open Source Documentation

I'm back working on the Fuse products again and couldn't be happier. The fact that they are commercial offerings of open source projects makes working on them more interesting than working on commercially developed software. It is not that the products themselves are necessarily more interesting (although in this case they are), it is the challenges around documenting them that is more interesting.
In a purely commercial world, the whole process is controlled. The engineers are located within the boundaries of the company. They answer to managers that you can ping. The feature sets and release cycle are well defined and mostly static. The documentation requirements are usually spelled out by the product manager with some input from the writers. They are usually well understood early in the cycle. When the product ships, the documentation is frozen until the next release is planned.
In a commercial open source world, things are different. While some of the engineers work for the company, most of them are part of a larger community that are beyond the corporate wall. Feature sets and release cycles are planned, but the plans are usually changed due to unpredictable changes from the community. Documentation requirements tend to be fluid to match the product development process. Customers have a large influence on setting requirements for documentation. There is an expectation that improvements will roll out over the course of a products life cycle.
In addition there is the ongoing struggle between what to take from the community, what to offer back to the community, and what to keep as part of the commercial value add. Do you offer cleaned up versions of the community written documentation? Do you push content written internally back to the community? If so, what? What is the process for sharing content between the community and the internal documentation team?
Coping requires fluidity and focus. Being capable of changing when needed is crucial, but so isn't staying focused on the core value of what is being delivered to the customers. If a change doesn't make sense, you need to be able to see it.
The other thing that is crucial is a dedication to quality. It is far too easy to let quality slip in an effort to meet all of the demands. When you let quality slip, you let your value slip. The community can write documentation of questionable quality without paying for a writer or an offshore writer can be hired to do some rudimentary editing. Neither outcome is good for you or the customers. In the commercial open source market, customers do read the documentation.


No comments:

Post a Comment