Ionrock Dot Org

The other day in the break room I noticed an short headline on the cover of E-Content magazine regarding RSS. This sparked my interest since I am becoming more and more convinced that RSS/Atom will be a preferred format for almost all web based systems. My excitement quickly was destroyed when it became clear that the article saw RSS as a means of distributing potentially valuable information. In short, I was appalled.

After being in music and reading quite a few articles on how book publishers work, it is clear when it comes to content (creative or otherwise), the goal is one big hit. You have to make one release that pays not only for itself, but everything before and after it in order to be really profitable. This puts a high level of value on content because supposidely people buy it to gain access to it. While this may be the sad truth behind the music/publishing industry, it makes no sense whatsoever for organizations that publish as a means of support (read not revenue).

Take Nokia for example. They released the Nokia 770, a small internet tablet that runs a version of Debian and uses GTK+ for their toolkit. The great thing about this is that they have signed up the whole GNOME community as a resource. The platform is open, *users* are writing applications and the platform is well documented. This all happened because there was a community built around the technology. When a company makes a decision to charge for documentation they immediately lose the ability to create a truly vibrant and revenue building community. They are forced to rely on advertising and customer word of mouth where little to no momentum can be created.

The concept of momentum is very important because it makes it possible to push a product or technology over the edge. This is what has happened with Apple and their dedication to creating a culture behind the Mac. They now have a dedicated community that cares about the company and each other, which means they are like a good friend, sticking it out through good and bad times. Apple does this by getting customers excited about using their product and I believe ePublisher can do the same thing.

When you think of ePublisher as simply a product, you are missing the point. ePublisher defines a platform. The platform is simply a base for greater things. We have to get customers excited about the "greater" things the platform offers. The only way to do that is to get the word out and a great way to get the word out is through documentation.

The concern is always in reference to support. If you blog about chaining AutoMap jobs and rewriting job files and someone actually gives it a try then you are hosed because you can't support it. I would argue that if I "blog" about anything then there is no support period. The paper publishes an opinion page that is known not to be fact. We can publish blogs that are essentially the same thing. This is also the case with a Wiki. Wikipedia is seen a valuable resource, not because it is fact, but because it is relatively reliable and robust. If something is wrong on wikipedia, then the people behind the site are not responsible. Again, there is an inherit accountability on the reader to digest and analyze the content as being something they can use.

This is why it is silly to be so concerned about RSS/Atom for documentation and content. It is simply a mechanism for providing users more resources with less responsibility on the author. Assuming the organization does enforce some quality standards then the content should be helpful without causing a support nightmare. In fact, I believe that it could increasingly *decrease* support requests because there will be more resources that may fill in the gaps of traditional docs.

Today I am working on a project that integrates with Documentum. One good thing about the project is that I know there is a command line interface, so when it is all said and done, I can make something happen. The downside is there seems to be a .Net interface available that I have no access to at the moment because we have not paid for the developer documentation. This is ridiculous.

I realize that someone down the line felt that they could make good money off of people trying to be experts in their application. Making money is great, but stifling grass roots evangelism and community is anything but desireable with complex applications. Open source projects such as Apache are wildly popular because of great software *and* a great developer community. There are tons of howtos and blogs about setting up Apache to do some trick and that is why it is so successful.

Documentation allows for distributed knowledge when it is free. To use a network metaphor, this reduces bandwidth by pushing request for information to those willing to accept it instead of one source. In some cases it seems reasonable to require payment for an SDK, albeit I don't know of one. But I would never buy an SDK license if I didn't have the chance to read the docs beforehand. How would I know the insanely bloated prices I am paying for a few dlls and a pdf are going to be worth the bits they supply?

This is one great advantage of ePublisher as a platform. The SDK is XSL. There are some extension objects that are WebWorks specific and the model we use is not overly obvious, but the essence is that if you understand XSL, then you have the tools to do whatever you would like with ePublisher. I know we are working documenting and providing more resources (this blog reflects this). I know if anyone gets the bright idea of forcing folks to pay for our docs I will screaming no!

Recently I have been thinking about how you can make something "better". It is always tough because it is taking a very general concept and trying to pull concrete task from it. Specifically, I have been thinking about making ePublisher better. Fortunately, I feel qualified to be considered and ePublisher "user". Some may disagree with this, but the reality is I use it every day. Therefore, I know my suggestions are somewhat biased towards how I use the product. Of course, that may not be that bad!

One overarching issue that I think could be addressed is how to customize the XSL. Currently, we do everything in XSL, and I mean EVERYTHING! The code which kicks off an transformation is very basic. Traditionally it would look something like this:

result = TransformObject.ApplyXSLT( StylesheetFile, SourceNodeSetAsParam );

This is just pseudo code of course, but it suggests how you apply a transformation to an XML file and how you might pass in a node-set as a parameter. What we do is even simpler. Instead of passing an XML node-set that represents some document, we pass in an XML file that simply lists XML documents. The XSL is then responsible for finding the path of the actual data document we want to work with and loading it as a node-set. From a design perspective, what we have done is much more flexible because the XSL has no limitations on what it can do. It has the power to load whatever node-sets are available whereever it needs to. The downside is that every XSL file is responsible for loading node-sets, which makes the XSLs very difficult to understand and read.

I think my biggest improvement to ePublisher then would be to address this shortcoming. I believe the flexibility we provide is incredible and taking that away does not seem like a good idea. I always like the idea that someone could really hijack the format to do some amazing things. With that in mind, I would suggest a means of stubbing out the boilerplate aspects of the code so someone could have a simple means of getting to the node-set they need.

So, for example, in the XSL I would like to do something like this:

<xsl:variable name=\"vParagraphsInTOC\" select=\"wwloader:LoadNodeSet('wwdoc:ParagraphTOC')\" />

The 'wwdoc:ParagraphTOC' is something like the "type" that we currently use. I am sure we could come up with a large group of nice-to-have types that we can offer in addition to basic node-sets like the WIF. The user could even create a type from available types and resources. The downside is that things like the progress bar becomes less useful and I am not sure how we would handle checksums for the node-sets, but I think these are small issues. The log window does a better job of showing progress and it seems reasonable that whatever loads node-sets will check the corresponding physical documents for changes.

The big question is how would this make ePublisher better? Well, the biggest benefit is simpler XSLs. This would allow reasonable documentation for people to learn WebWorks specific details because there is no need for extra information in the XSLs. This might also promote better tools such as a Node Watcher that examines what nodes are available in a stage or XSL file. The biggest benefit is that people who understand XSL have a much lower entry point for making changes and debugging changes. Right now, it is very difficult to find what nodes you need and how/where you can get them. Beyond this, it is difficult to debug issues when they crop up and whether or not the approach to the problem is correct.

One thing I should make clear is that the XSLs should not really change. The code should do the same things and any sort of boiler plate or skeletons should be cascade like we do with the formats. Likewise, it would be helpful to actually be able to write out the "full" version of the XSL if needed. That way a new format could add back in the progress aspects if required before the "abridged" XSL is reached.

I am not sure if this would really make ePublisher "better" but I am sure it would make my life easier. I realize I am not the "customer" but I am definitely a user.