FuseSource just released enterprise versions of their message broker and ESB. In addition we released a new management console and a new version of Fuse IDE. Together the products aim to make it easy for companies to consume open source integration technology.
As part of the effort to make the technology easier to consume, we beefed up the documentation. We continued the upgrades to the messaging documentation. We added some more introductory information and overview documentation. We did more work on making the content more procedural as well.
The most exciting thing, at for me, was introducing ePub versions of all of books. Now users can access the content offline on their mobile devices including iPad, Android, Nooks, and any other e-reader.
Getting the DocBook to ePub transform to work in our build environment has been a long term goal of mine. The DocBook XSLT project comes with support for ePub, but it requires running support programs. I needed it to all work using just XSLT and Ant which proved harder than I had anticipated. The support programs are just used to do the packaging, so I figured that it would be easy to use Ant scripts to do the packaging. I was wrong. Getting everything in the right place was tricky, but the real catch was getting the encoding right. There were also some issues with namespaces getting in the way. The community, as always, was helpful in sorting through the issues.
Check out the end result in the Fuse MQ Enterprise and Fuse ESB Enterprise at the FuseSource Documentation page.
May 17, 2012
May 10, 2012
We Only Notice When It Is Bad
One of the frustrating things about working in technical documentation is that people only notice the documentation when their is something wrong with it. Customers rarely mention that the documentation is excellent because they just expect it to be complete and thorough. The comments only ever come in when the documentation does not meet a customer's needs. Sometimes the complaints about the documentation are really about a lack in the actual product, but the user only notices it when it they are looking at the documentation.
This fact has several impacts on documentation teams:
The most obvious is that writers can easily get demoralized. It is imperative for internal customers-the tech support team, the sales team, the development managers, the product managers-provide some positive feedback. The documentation team will get plenty of negative feedback, so there is no danger that their heads will swell.
Because customers rarely think about the documentation, they rarely provide requirements for the documentation. This means that the product management team rarely provides detailed guidance for the documentation team. Most often, the guidance is that we need to document the new features. Occasionally, if a customer has complained about something it is listed as a requirement, but without any clear information about what the underlying issue the customer is having. The requirement will be something like "we need more documentation about Java development."
The largest impact that customer's lack of thinking about documentation is that it results in a lack of investment. The lack of investment is monetary, personnel, and time. Because customer's generally don't have requirements for documentation, the impression is that it isn't important. Because the only comments that are received about documentation, the impression is that the documentation team is less than good. The result is that development teams are always looking for ways to hire less writers and squeeze more efficiency out of the documentation process. The result is that the documentation usually gets poorer and the complaints go up.
Curating knowledge for complex technical products is an inefficient process. Dragging information out of SMEs takes time, organizing the information takes time, trying out the processes takes time. There is no real way to improves the speed of these steps. The push for modular, context free documentation is an outcrop of this push for efficiency, and it also, generally, creates poorer documentation. Context is an important part of written content.
What can we do to address these issues? Educate internal customers about the importance of documentation. Make sure they understand that the fact that customers complain shows that they care. The fact that they don't mention the documentation probably means that the documentation team is doing a good job. As writers we need to remember that silence from the customers is the biggest compliment.
This fact has several impacts on documentation teams:
The most obvious is that writers can easily get demoralized. It is imperative for internal customers-the tech support team, the sales team, the development managers, the product managers-provide some positive feedback. The documentation team will get plenty of negative feedback, so there is no danger that their heads will swell.
Because customers rarely think about the documentation, they rarely provide requirements for the documentation. This means that the product management team rarely provides detailed guidance for the documentation team. Most often, the guidance is that we need to document the new features. Occasionally, if a customer has complained about something it is listed as a requirement, but without any clear information about what the underlying issue the customer is having. The requirement will be something like "we need more documentation about Java development."
The largest impact that customer's lack of thinking about documentation is that it results in a lack of investment. The lack of investment is monetary, personnel, and time. Because customer's generally don't have requirements for documentation, the impression is that it isn't important. Because the only comments that are received about documentation, the impression is that the documentation team is less than good. The result is that development teams are always looking for ways to hire less writers and squeeze more efficiency out of the documentation process. The result is that the documentation usually gets poorer and the complaints go up.
Curating knowledge for complex technical products is an inefficient process. Dragging information out of SMEs takes time, organizing the information takes time, trying out the processes takes time. There is no real way to improves the speed of these steps. The push for modular, context free documentation is an outcrop of this push for efficiency, and it also, generally, creates poorer documentation. Context is an important part of written content.
What can we do to address these issues? Educate internal customers about the importance of documentation. Make sure they understand that the fact that customers complain shows that they care. The fact that they don't mention the documentation probably means that the documentation team is doing a good job. As writers we need to remember that silence from the customers is the biggest compliment.
Subscribe to:
Posts (Atom)