jwiles
jdub's webworks web log

The 2008.2 Release of the ePublisher Platform went live today. This release includes the Eclipse Help Format. I have just posted a wiki page which documents the items which are peculiar to the Eclipse Help format.

I posted two new wiki articles. The first is a general outline of ePublisher URI Resolvers. The second is documentation for wwtransform:super, a cool new URI available in the 2008.1 runtime.

ePublisher 2008.1 is here. Happy Q2.

One of the more interesting aspects of the ePublisher 9.3 Release is the introduction of the Xml Adapter. By default, this Adapter allows users to generate output from DITA source documents. However, perhaps more significantly, it carries with it the ability to configure ePublisher to accept ANY input source.

To demonstrate this functionality, during RoundUp 2007, we showed the Xml Adapter publishing content from the WebWorks Wiki to WebWorks Help 5.0. It was our intention at that time to make this project available online. With this objective in mind, I've added a page in the RoundUp section of the WebWorks Wiki. This page includes the project I used to publish content during the Day 2 Keynote. It also includes instructions for modifying which WebWorks Wiki content is included in the project. This effectively gives you the ability to create your own WebWorks Help 5.0 help system, or any other ePublisher supported output Format, including ones you have developed, using content from the WebWorks Wiki.

In the coming weeks, I plan to publish a tutorial on developing a custom Xml Adapter from scratch. Stay tuned.

Uri Adapter

Currently, we are working on updating ePublisher to run on Windows Vista. Also I am working on updating ePublisher's FrameMaker Tool Adapter to support FrameMaker 8. One of the more challenging aspects of this latter task is adding support for FrameMaker 8's new "conditional expression" feature. This feature allows the end user to define a logical expression which should be used when applying visibility settings to conditional segments of a FrameMaker document.

On the FrameMaker side, it seems that retrieving the information from the new FDK is relatively trivial. The more interesting challenge may be how to present this new paradigm to ePublisher users. At first we decided to wrap the old mechanism in a radio button region, and add the new option to a new radio button section.

Initial efforts to design this approach have fleshed out an important shortcoming in the current "unified" interface that ePublisher presents for defining condition visibility. Specifically, different source formats have different ideas of what "conditions" are and how they are implemented. DITA provides a "tag-like" approach which allows filtering for purposes other than visibility. If your input is Word or a version of FrameMaker below 7.x, you have no use for an expression option.

This revelation is causing us to pursue an alternative approach. The idea is to move Conditions out of the hybrid Conditions/Variables dialog, altogether, and model a new Conditions dialog, after the existing Cross Reference Rules dialog. As with Cross Reference Rules, this approach would allow us to display a Conditions dialog appropriate for each input format. No mock-up yet, but stay tuned.

Ingredients

• I have a tendency to want to write a program first and design it later. Given that my academic background is not computer science, I often feel that I'm missing something about spec writing, design, etc. And I am. I believe that the penultimate of hubris, a path I traverse more often than I would care to admit, is to make any emphatic statement about a thing for which one has little or no first-hand knowledge.
• Recently, one of my fellow developers gave a presentation on UML and highlighted the differences between forward and reverse modeling. Reverse modeling builds an abstract representation from an existing implementation. Forward modeling is the opposite. Build the model first, write the code second. Both are valid approaches to modeling.
• Last Tuesday I attended the Agile Austin meeting with Ben. One thing which really resonated was the speaker's assertion that you need to shape a work flow to suit your process. As with any evolutionary system, there must be room to specialize.
• In film, there is a certain time of day, around the sun's rising and setting, when the natural lighting is ideal, which is referred to as the "magic hour". On a shoot, entire days and weeks of preparation may be all centered on getting a few seconds in the can during this small window.
• Last week I read this blog entry by Joel Sposky. In this entry he writes (and I'm pulling this quote out of context, so I highly recommend that you read the entry, though for the sake of brevity, I will summarize the context as: a statement on the relationship between a software spec and the resulting program):

  ...the bottom line is that if there really were a mechanical way to prove things about the correctness of a program, all you’d be able to prove is whether that program is identical to some other program that must contain the same amount of entropy as the first program, otherwise some of the behaviors are going to be undefined, and thus unproven. So now the spec writing is just as hard as writing a program, and all you’ve done is moved one problem from over here to over there, and accomplished nothing whatsoever.

Soup:

So my tendency to want to build first, design later, may not be entirely misguided. It seems to me that the real trap here, is the "which is better" conundrum. Both may be valid. This soup is about the way I prefer to program, which may be summarized in the following order:

1. Spend a little bit of time thinking about what I want to write. If someone else is coming up with the idea, spend a little bit of time brainstorming with them. DON'T WRITE ANYTHING DOWN YET.
2. Implement the brainstorm immediately. Within a few days, or a week.
3. Analyze the result (document and model; often this ends up in a readme) and recurse.

Some things to note about this process. First, the post-brainstorm implementation implies a managable chunk. It's not to say that you can't build large apps. But build incomplete representations of the large app first.

For instance, if you're going to write a classic MVC app and each aspect will probably require several weeks to implement, then the first offering might be a simple glue code program which interacts with stubs that print statements about the "real" code that should ultimately exist there. That is, if a controller needs to do a series of complex database operations, then in the initial version, the controller will print a message like, "doing complex database operations...".

The point is, nothing should derail the programming "magic hour" which follows a good brainstorming session. Things can be refactored and analyzed later. In the beginning, generate velocity. Ultimately the resulting intertia can be much more easily molded into the desired result. But as with bicycles and sailboats, it is very hard to steer a thing which has no motion, or in programming, doesn't do anything.

Cleanup:

This, by the way, IMO is the primary reason for the ubiquity of Hello World.

Obviously, this article is mostly outloud thinking about my own process. It's unoriginal, plagiarist and derivative. It's specialization.

I've added a Tip to the WebWorks Wiki. This is an example project which demonstrates using a custom FTI setting to use a custom *.hhc file for HTML Help, rather than the one ePublisher generates by default.

Wiki Tip

I've published a draft of the article on FTI. I'd like to formally request comment from anyone who has a cycle or two to go through it; what's good about it, what's bad about it, etc. You can email me directly and I will try to update it as needed. Alternatively, if you've got a login to the wiki, please feel free to post any feedback directly in the draft.

Currently the Draft does not include the wiki format as I am still debating the best way to make this available. Can I assume that our users have access to a directory diff program like AraxisMerge or WinMerge? If not, I might try to deliver the format with an HTML diff report, with the idea that this might be the easiest way to keep track of the changes I made to Ben's base wiki format.

Update: I've added the wiki format to the article, along with a brief description of the contents of the format. Missing is a detailed description of how the Wiki format was created, as this probably belongs in another topic.

We finished RoundUp yesterday. This was such a valuable event for the WebWorks community and I'm so grateful for everyone who attended and participated. I was very happy with the way the entire event went, except for the problems with the demo at the end of my FTI presentation.

I have the impression that I promised a few more things than I tracked. Here in brief is what I plan to make available. Please ping me if you feel I've forgotten anything, or if you have any questions on the materials as they are made available.

Items To Post From RoundUp 2007

• Resources Adapter (rAdapter)
• wiki-prefix, wiki-suffix example
• FTI Documentation (wiki.webworks.com)