Wrycan

Misunderstood Complexity

2010-01-06T14:13:00.008-05:00

The biggest failing we run into time and time again around content / digital publishing projects is the misunderstanding of where the complexity lies.

When someone buys an RDBMS, they don't assume that simply installing such a system and some trivial configuration will solve their data problems for them or produce their data-driven software application. They understand that this is just a tool which they will use to do the large amount of work of analyzing their data needs, designing a schema, and implementing it in their RDBMS along with application code to use it.

However when they buy a content management system, or some other content tool, they have a tendency to expect that it WILL fill all their content needs, and that the analogous work of analyzing, designing and implementing are minor. While people understand that "data" is hard, complex, a lot of work etc., they seem to assume content is relatively easy.

This is not unlike the scenario with a lot of other software projects where some out-of-the-box middle-ware is expected to provide a solution and the task of analyzing and defining their needs and of designing a solution (even in terms of the "parts" the middle-ware supplies) is vastly under-estimated.

A content management / publishing system (and by this I mean not specifically a CMS, but the whole system and process by which a company manages and publishes its content, including whatever software systems and tools are used to facilitate this, and the human processes around that) can be enormously complex. It's not the same as everyone else's, and there's not some off-the-shelf system that simply does it all automatically. The commonality of "everyone has content" is about as significant as the commonalty of "everyone has data". It's the details around "what kind of" and "how used" that drastically overshadow the commonalities.

The software tools, wherever they fall on the out-of-box / highly customized / home-rolled spectrum provide pieces of the solution, not the big picture, and that big picture, that overall design, is needed to even know how to put those pieces together. In fact, if you haven't figured out your overall design in detail, then you don't really even know what the pieces are that you need.

This big picture is a domain model. You have a business domain around your content, and the different sorts of content, the roles they play, and the processes that go into producing, maintaining, publishing (by which we include making available through some specialized web application) are all parts of this domain model. These software systems and tools you've bought do not provide that domain model or those elements of it. They may provide you with means of modeling them or implementing your model. But if you don't start with that model...well, good luck.

This is the understandable human failing of wishful thinking. Analyzing your needs and designing that model is HARD. It's not the sort of thing that business people, or content production people are good at or know how to do. Software people, on the other hand, who do (the competent ones) know how to do that, typically don't understand the content production and publishing domain, and communicating a deep understanding of those needs from one group to the other is also very hard. Unfortunately content-oriented software specialists are both rare, not commonly recognized as a specialty, and (largely because of the misconception outlined above) undervalued.

NAVSEA: Wrycan and Altova Project Case Study

2009-05-29T11:42:00.001-04:00

Thousands of technical processes. CAD drawings. Schematics. Wiring diagrams. Safety and Training requirements. Piddle packs.

What do all of those items have in common? They are all parts of a complex Navy system that were documented in an antiquated format.

Wrycan was chosen by NAVSEA to assist in converting tens of thousands of pages of existing documentation into XML to comply with the Navy document model. Wrycan used Altova's XML editor as a key component in the editioral process. Modules from the Wrycan XMS were used to facilitate workflow and document assembly while Wrycan's XSL Consultants developed the high-end PDF output.

The result is an end-to-end process that allows NAVSEA to author, edit, review, approve, publish and distribute large volumes of technical and process information to those who need it.

Wrycan and Altova have just published a case study outlining the project. Read it to find out how Wrycan and Altova worked together to ensure the project was a success.

Interested in talking about your content with us? Get in touch.

~

Product Announcement: XMS Correlation Tool

2009-04-20T08:00:00.007-04:00

Cambridge MA - Say goodbye to managing textbook correlations in Microsoft Excel and Microsoft Word. Wrycan is happy to announce the release of a new product, the XMS Correlation Tool.

An innovative product for educational content publishers, the XMS Correlation Tool is built to solve one of the most common challenges facing educational publishers today, creating and managing educational standards correlation data.

The XMS Correlation Tool is a web-based system built on top of Wrycan XMS that allows you to create, manage and utilize correlation data for all your education content, regardless of format.

The XMS Correlation Tool supports various correlation scenarios including:

correlating content to state and national standards
correlating content to custom intermediary standards
correlating custom intermediary standards to state and national standards

The once tedious job of creating correlations in spreadsheets and text files can now be done using a drag and drop interface, allowing correlations to be created and stored across content and standards with ease.

figure 1. correlation web interface

Sound interesting? Want to see more? Contact us to get more information and to set up a demo.

About Wrycan
Wrycan, Inc., a privately held company, was founded in 2002 to provide content-centric products and services to companies looking for innovative approaches to content creation, management, publishing and delivery. Our primary product, Wrycan XMS, is a content management platform built on years of experience solving "the hard content problems" for our clients. Wrycan XMS includes robust content repository, workflow and publishing facilities that together provide a solution for the most complex content management/utilization needs.

Your content is innovative, your content tools should be innovative too.

For more information about Wrycan's products and services, please visit our website, www.wrycan.com or contact John Corkery, Director of Business Development (john.corkery (at) wrycan.com)

~

How to Customize Attributes in the DITA Open Toolkit PDF Plugin

2009-02-23T09:00:00.002-05:00

This tutorial uses the DITA Open Toolkit 1.4.2.1 and the corresponding PDF plugin release, and Wrycan's demo text. This assumes you have a working DITA environment and can run the default formatting with PDF plugin. If you don't know how to do this, contact us and we can post an example! We will be working in the demo/fo/Customization directory of the open toolkit as shown in the image below.

1. In this example, we are going to customize the <codeblock> element by increasing the font size, changing the font color and weight, and modifying the background color. Our default code block looks like the following before any changes:

and the dita xml content looks like:

<codeblock>/* I should have green text and a red background */

<xsl:template match="dita">

</xsl:template>

</codeblock>

2. In order to modify the <codeblock>, we first need to figure out which attributes to change. The method I find most useful is to run a full-text search the demo/fo directory. Searching for the term "codeblock" yields a few results, one of which is demo/fo/xsl/pr-domain.xsl and the template is found on line 46: <xsl:template match="*[contains(@class,' pr-d/codeblock ')]">. Examining this template shows us that we want to modify the "codeblock" attribute set as shown on line 48: <fo:block xsl:use-attribute-sets="codeblock" id="{@id}">. Looking at the text search again, we can see that the "codeblock" attribute set is found in demo/fo/cfg/fo/attrs/pr-domain-attr.xsl on line 41: <xsl:attribute-set name="codeblock">. The next step is to customize this attribute set.

3. In order to customize this attribute set, copy demo/fo/Customization/fo/attrs/custom.xsl.orig to custom.xsl and copy the codeblock attribute set into the new XSL. We are going to modify the background color, font color, font size, and make the font bold. In order to do this, we only need to specify the attributes that we are going to change, so the resulting block of code to add looks like:

<xsl:attribute-set name="codeblock">

<xsl:attribute name="background-color">#dc7f72</xsl:attribute>

<xsl:attribute name="font-size">12pt</xsl:attribute>

<xsl:attribute name="color">#005511</xsl:attribute>

<xsl:attribute name="font-weight">bold</xsl:attribute>

</xsl:attribute-set>

Note, that we could also copy over the entire codeblock attribute set and modify that, which would results in the code below. Both of these should produce the same output.

<xsl:attribute-set name="codeblock">

<xsl:attribute name="space-before">0.4em</xsl:attribute>

<xsl:attribute name="space-after">0.8em</xsl:attribute>

<xsl:attribute name="white-space-treatment">preserve</xsl:attribute>

<xsl:attribute name="white-space-collapse">false</xsl:attribute>

<xsl:attribute name="linefeed-treatment">preserve</xsl:attribute>

<xsl:attribute name="wrap-option">wrap</xsl:attribute>

<xsl:attribute name="background-color">#dc7f72</xsl:attribute>

<xsl:attribute name="font-family">Monospaced</xsl:attribute>

<xsl:attribute name="line-height">106%</xsl:attribute>

<xsl:attribute name="font-size">12pt</xsl:attribute>

<xsl:attribute name="keep-with-previous.within-page">always</xsl:attribute>

<xsl:attribute name="color">#005511</xsl:attribute>

<xsl:attribute name="font-weight">bold</xsl:attribute>

</xsl:attribute-set>

4. The last step is to tell the plugin that we have made customizations. In order to do this, copy demo/fo/Customization/catalog.xml.orig to catalog.xml and then open the copied file and edit the 6th row to uncomment the code from:

to:

and save the file.

5. This should create the output below for the <codeblock> element. There are many different ways the attributes can be customized and this is just one small example. If you have some ideas for other examples you would like to see, contact us!

Create SVG-based charts "on the fly" using XML and XMS

2009-02-16T06:00:00.002-05:00

In order to really take advantage of XML-based content you need more than just an XML-aware database or repository. We built the XMS Content Management System to provide the right tools and facilities to unlock and make use of all the inherent value in well-designed XML content/data.

A cool yet practical example is to take a simple data set and create charts using XML and SVG. In a recent client project we needed to create reports that indicated how assets were distributed across geographies. Aside from just showing a table of the data (See figure 1), we wanted to produce a world map that would show exactly how the assets were allocated across each region. In this how-to I will explain how this was done using the XMS but most of the steps are general enough you should be able to replicate most of them with other system. If you have questions about how to do something like this using a different system feel free to contact us.

figure 1: table of geographic asset distribution

The first step to adding a map visual for this data was to find a good SVG map. We found some good options released by the CIA for public use on Wikipedia.

The map was very well defined and each country had it's own separate structure. The map was black and white but we wanted to add color to each region to make it easy to differentiate. Since we were using Morningstar's regional data we had to modify the SVG map to group the countries into the correct regions and give them a specific color. This was easy since the CIA used the proper two character country code for each SVG object. A few CSS changes yielded the following in the SVG:

figure 2: SVG with Morningstar region mappings

You can download a copy of the modified SVG here (~2MB).

Next, we loaded the SVG map into the XMS along with some sample data sets containing examples of asset allocation over geographic regions. To create the publication that would produce the report containing both the table and the map, two XSL transforms were written; one to produce the HTML report with the table (report.xsl) and one that would produce the correct SVG (map.xsl). Together these XSL transforms would create the report by generating the table of results and the PNG version of the map.

The XMS has a powerful publishing module which allowed us to process the SVG map and embed the result into the report. In this example the report.xsl would do most of the work while the map.xsl would simply assign the correct percentages to the regions of the map in the SVG. A sample of the XSL used to assign the precentages in the SVG map is shown in figure 3.

figure 3: sample of the map.xsl showing the regional percentages being added (shown in XMLSpy from Altova)

The resulting SVG is then rasterized to a GIF, JPG or PNG and the URL to the new image would be "handed back" to the report.xsl and added to the resulting report HTML. The XMS uses XEP from RenderX to convert vector graphics into raster formats. You could use other tools like Batik to get the same result. The result report combining both the table and the map looks something like the following:

figure 4: resulting regional report

Pretty slick. Of course we did the same for other charts (i.e. pie charts) but the map example was the most interesting. Another advantage of using SVG is the fact that it is vector-based, meaning that PDFs generated with the native SVG (not rasterized) will look very polished.

How to Modify the Cover Page in the DITA Open Toolkit PDF Plugin

2009-02-11T08:00:00.000-05:00

This tutorial uses the DITA Open Toolkit 1.4.2.1 and the corresponding PDF plugin release, and Wrycan's demo text. This assumes you have a working DITA environment and can run the default formatting with PDF plugin. If you don't know how to do this, contact us and we can post an example of how to do this! We will be working in the demo/fo/Customization directory of the open toolkit as shown in the image below.

1. With our sample content, the cover page of the document contains plain title text slightly above the center of an empty page:

Wrycan® Lorem Ipsum Test

We are going to modify this so that our company logo appears below the title text.

2. In order to modify the cover page, we first need to figure out which stylesheet creates the cover sheet. The method I find most useful is to run a full-text search the demo/fo directory. Searching for terms like "cover" and "cover sheet" yield no results in this case, so the next thing to do is look at the xsl files themselves. Starting with demo/fo/xsl/fo/root-processing.xsl we can see there is a template called createFrontMatter. Searching in the XSLs for this template reveals that it is in demo/fo/xsl/front-matter.xsl.

3. The next step is to modify the template. In order to do this, copy demo/fo/Customization/fo/xsl/custom.xsl.orig to custom.xsl and copy the createFrontMatter template into the copied XSL. The logo image is going to be added below the subtitle, so below the template call with the "set the subtitle" code comment. Add the code below underneath the subtitle template:
<fo:block text-align="center" width="100%">
<fo:external-graphic src="url({concat($artworkPrefix, '/Customization/OpenTopic/common/artwork/logo.png')})"/>
fo:block>

The parameter $artworkPrefix is passed in during the build process and the string "/Customization/OpenTopic/common/artwork/" is created for where our logo image is going to end up during processing.

4. Now that the code has been added, we need to actually add the logo. To do this just copy an image file of the name logo.png into demo/fo/Customization/common/artwork folder or use ours as shown at the end of this post.

5. The last step is to tell the plugin that we have made customizations. In order to do this, copy demo/fo/Customization/catalog.xml.orig to catalog.xml and then open the copied file and edit the 10th row to uncomment the code from:

to: <uri name="cfg:fo/xsl/custom.xsl" uri="fo/xsl/custom.xsl"/> and save the file.

6. This should create the output below on the cover sheet of the pdf. There are many different ways the cover sheet can be customized and this is just one small example. If you have some ideas for other examples you would like to see, contact us!

Wrycan® Lorem Ipsum Test

How to Customize the DITA Open Toolkit PDF Plugin Output to Remove "on page xx" Text for Cross References

2009-02-07T16:16:00.014-05:00

This tutorial uses the DITA Open Toolkit 1.4.2.1 and the corresponding PDF plugin release, and Wrycan's demo text. This assumes you have a working DITA environment and can run the default formatting with PDF plugin. If you don't know how to do this, contact us and we can post an example of how to do this! We will be working in the demo/fo/Customization directory of the of the open toolkit as shown in the image below.

1. We will customize the cross references so that there will be no "on page xx" displayed. The DITA markup that we are customizing looks like the following in XML:

<p><b>This xref link to <xref href="PellentesqueConsectetuer.xml#pellCon/sampleXREFtarget" scope="local"/> is a sample link to an element within this topic.<b><p>

And the default output looks like the following in the PDF output:
This xref link to Table 3: Sample XREF Target on page 11 is a sample link to an element within this topic.

2. Next, we need to find the code in the XSL where this occurs, and then create the customization layer to override this code. To do this, a full text search of the demo folder can be done for the text "on page." One tool that can do this quickly is Edit Plus which reveals that in demo/fo/cfg/common/vars/en_us.xml, on line 258, there is a variable that is set with the name "On the page" as shown below:

3. Another search can now be done for the text "On the page," which shows that demo/fo/xsl/fo/links.xsl on line 371 is where this variable is being called, in the template <xsl:template name="insertPageNumberCitation">. The next step is to integrate this template into the customization layer.

4. A quick and easy way to do this is to copy the file demo/fo/Customization/fo/xsl/custom.xsl.orig to custom.xsl. Then open it and copy/paste the original insertPageNumberCitation template from links.xsl. This template has an <xsl:otherwise> containing the "On the page" variable, so in order to remove the "on page xx" text, this otherwise case should be removed by deleting everything from and including <xsl:otherwise> to <xsl:otherwise> and save the file. Note: If you are going to be making a lot of customizations to the fo plugin, then it might be a good idea to utilize the <xsl:import>

function to better organize your customizations. If you have any questions about this method, feel free to ask and we'll do a post on it!

5. Finally, the fo plugin needs to be told that customizations have been added. In order to do this, copy demo/fo/Customization/catalog.xml.orig to catalog.xml and uncomment line 10 from:

to
<uri name="cfg:fo/xsl/custom.xsl" uri="fo/xsl/custom.xsl"/> and save the file.

The creation of the customization layer is now complete! Re-run the pdf and see the results. In our case the output now looks like the following:
This xref link to Table 3: Sample XREF Target is a sample link to an element within this topic.

If you would like to see any other ways to customize the DITA Open Toolkit, contact us and we can provide one!

Design, but only for the sake of design

2009-01-13T13:34:00.005-05:00

One of the things that we try very hard at as a company is to not over complicate our software and to be too "designy". There are many principals considered to be critical to achieving good design (graphic, UI, usability, etc) and these principals are hotly debated in hundreds of blogs.

There is one principal that crossed my mind two weeks ago was "Design should not get in the way of simple tasks/interaction".

Driving a car can be a very intense experience... so many things happening around you and so many inputs that must be processed in real time. There are many things in a car that are designed to make processing external events as easy as possible. Take for instance the brake lights on the back of a car. You have probably heard many people quip that someone should invent a brake light that reacts differently depending on how hard the brakes are applied. If someone just taps the brakes, the light would be more dim than if someone slammed on the brakes. Sounds good in principal but there is at least one reason why this hasn't been done: "less is more". With the current system a driver only needs to process 2 states; brake and no brake. Sure, people will infer how hard someone has brakes based on seeing the brake lights and then seeing how quickly the car is slowing... but that is something that done by evaluating the environment around the car, not left up to some series of lights, the brightness of lights and the car-maker's implementation of such a standard.

Another task that is important in a car, especially with younger drivers, is the need to know how fast you are going. The more you drive the more you get a feel for how fast you are going so you are checking the gauge less and less often. Even the speedometer is never dead on anyway but it is still an important task that is performed in a car dozens to hundreds of times on each and every car trip. I had never thought how design could negatively influence this interaction until I got a rental car, a 2008 Ford Focus.

It has been my experience that even with the changes in the speed limits in the past 20 years one things remains fairly standard: most speed limits are based on "5" (35,45,55,65). Most cars have these speeds well denoted on their speedometers allowing you to check on your speed very very quickly. So quickly in fact you probably never even realize you are doing it. In the Escape it seems that Ford wanted to apply a "slick" design to the speedometer (all their gauges in fact). I have to say, what was once an easy task became much harder. Check out the image below from US News and World Report (apologies for the small image)

Can you quickly tell where 65 is? How about 55? When I first got the car I was equating 55 with the dash between 40 and 60.. only for my amazing math skills to take over and realize that it was in fact 50, not 55. So that leaves me to get the speed somewhere between that little hash mark and 60 to achieve 55. Now again, I realize that as an "experienced" driver this isn't so bad, but imagine a 16 year old, trying to focus on a million new things when driving and trying to make sure he/she is going the correct speed. Even worse, imagine this car during a driving test with a state cop in your passenger seat.

As far as I am concerned Ford took something that should be a simple task and then "designed" all the simplicity out of it.

Start simple and let it evolve...not quite

2008-12-02T02:14:00.002-05:00

One of the items that I follow in my Google Reader is the 37Signals blog Signal vs. Noise. 37Signals built their business on creating simple and elegant solutions for tasks such as project management, contact management, collaboration, etc.

Last week one of their posts included the following quote that I found rather interesting:

"A complex system that works is invariably found to have evolved from a simple system that worked. A complex system designed from scratch never works and cannot be patched up to make it work. You have to start over, beginning with a working simple system."
—
John Gall

Initially I liked the quote and felt that it fit the way in which we have built our products. But the more I thought about it the more I realized how the underlying architecture of our system is actually quite complex, and has been from day one. The design is drawn from years of collective experience dealing with complex content management problems as well as some luck as we were fortunate enough to work on some pretty interesting bleeding edge content utilization companies along the way.

All that experience lead to a product development plan where we invested a significant amount of time in designing our system and then set out to implement the most basic items first. We found that there was no way to just account for the most basic items in our design, but wherever possible our design called for basic components to be used as the foundation for more complex system functions.

My interpretation of the quote as it pertains to what Wrycan has done is this:

"No matter how complex the problem you intend your system to solve, it is better to implement a hand full of simple items and get it in front of users and then build from there. Version 1.0 is no place for complex features. Get the basics right first."

So did that mean our customers weren't calling and emailing asking "why can't we do this?", or "why can't we do that?" No, of course they did. But we have found that a system does the basics really really well more than makes up for the items our customers thought were missing. Once we started releasing more complex features we were able to incorporate customer feedback which only made our customers more engaged and invested in the product

Wrycan/Altova Case Study

2008-11-15T10:30:00.000-05:00

As an Altova and long time users of Altova's tools, we are often called upon to help Altova's customers get the most out of tools like XMLSpy and Mapforce.

In this case we were asked to help Fitz and Floyd, a leader in design and manufacture of hand painted ceramic giftware. Fitz and Floyd needed a way to interface their existing Oracle-based CRM system to their new Web-based storefront application from MarketLive, the leader in e-commerce software solutions.

The result was a simple transaction manager that allowed the transactions handled by the MapForce-generated, Java-based data integration applet to be scheduled, processed, and logged.

figure: example of web-based transaction system interface

Read the full case study:
Altova partner uses Mapforce to create a modern, Web-based, Oracle to FTP system interface for a manufacturing client’s online storefront..

Wrycan featured in Atlassian Case Study

2008-11-05T13:11:00.000-05:00

For the last couple years two of the components of our development process have been JIRA and Confluence, two products made by Atlassian. For those that aren't familiar with these two products, JIRA is an issue tracking system and Confluence is a knowledge base (aka Wiki).

We use both products very extensively to "track everything that we don't want to forget". Both tools give us the ability us to manage a large number of projects relative to our size. We are a company of less than 10 but routinely manage 10+ projects at one time. An overview of how we use JIRA and Confluence to manage our consulting projects can be found here.

Atlassian has attempted to profile many of the small companies that utilize their products and Wrycan just happened to be at the right conference at the right time.

Read the case study here...