For the impatient, you can skip the rest of this, and just download a WAR from my Google Docs account at https://docs.google.com/a/ipov.net/leaf?id=0B1u9Agj_s0HLZWZhNWFjNzItNzI4Ny00NzAxLTlhMmMtYjhiZmIxYzdlOGQ5&sort=name&layout=list&num=50 Just expand the WAR and add your help plugin(s) to the WEB-INF/plugins/ directory.  Make sure that your plugins to not depend on anything other than the Eclipse Help bundles and you should be fine.  I’ve noticed while preparing this, that a number of help plugins/bundles actually declare the same dependencies as the plugin they document, thus making running standalone impossible as the OGSi container will refuse to activate them.  Hopefully someone will take over hosting this WAR for me, it would be great if Eclipse.org made it available for download as part of their normal release schedule, but that’s asking for a lot.

Anyway, in case its useful to others, or I need to reference this in the future, here’s what I had to do to get this WAR file running.

First, I google’d the issue; I found a smallish number of blogs already out there, and the offical documentation (e.g. http://help.eclipse.org/helios/index.jsp?topic=/org.eclipse.platform.doc.isv/guide/ua_help_war.htm).  Warning: Many of the blogs are for an older version of the runtime, and will instruct you to place files under WEB-INF/eclipse, this is incorrect and will result in the web-app failing to start.  The instructions in the Eclipse help are correct.

From the instructions:

1. This is correct enough, although you don’t really have to use a temporary directory, I just extracted the plugin JAR directly to my local development install of Tomcat to facilitate testing, e.g. to %TOMCAT_HOME%/webapps/help
2. Note that you’ll need Eclipse Plugin Development Kit for this.  I also ran into a problem with using my install as my target platform, some issue with the JUnit addon for PDE, so I had to define a platform and exclude the JUnit plugin, not a big deal, but an extra step.
3. Note that this step assumes you extracted the “temporary” directory referenced at the start as “webapps/help”
4. Again, not that if you copy help plugins which declare extra, usually unneeded, dependencies, the help system will start, but will exclude those help plugins.  You can edit the WEB-INF/web.xml to add the -console option so that you can access the OSGi console and get some diagnostic information on why the plugins aren’t started (it isn’t logged to the Tomcat log files).
5. Downloads of the ServletBridge.  I haven’t experimented, but I placed both files into my webapps/help/WEB-INF/plugin, and then also copied the org.eclipse.equinox.servletbridge to my WEB-INF/lib directory.  This seemed to work fine.
6. Note that previous versions of the instructions tell you to “extact the servletbridge.jar” form the plugin jar, this is no longer correct.
7. No other variations/extra information should be needed.

Comments and addition information are welcome.  I hope this helps others, and maybe someone can eventually get the Standalone Infocenter WAR added as a standard part of the Eclipse release builds.

I’ve been interested in doing some work with DITA, and currently the DITA-OT processing code seems like the main viable way to do so, at least without paying an arm and a leg.

One of the first things I noticed, other than the spotty documentation of the toolkit (talk about the cobbler’s family being the last to get new shoes!) was that the basic xhtml output is, well ugly.  So, the first thing I did was to open up some output using Firebug and take a look at the generated styles.  “Ok,” I said to myself, I can use a custom CSS file to fix the majority of the issues here… then I looked at the main table-of-contents.  The ToC file has no class attributes on any elements, and imports the same CSS file as the content pages.  The content pages have class attributes, so it should be possible to write some CSS to target both, but I really didn’t like the idea of leaving the CSS for my ‘menu’ so generic, it would be just too easy to have it accidentally apply to some other elements or something.  So I started digging into how to customize the ToC output.  It turns out there isn’t any extension point to override the processing in the way there is for the main xhtml, or other main content types.

I looked at the tocjs plugin, which does some nice effects, using the YUI tree; but its pretty basic (the tree) and we tend to use either jquery or dojo, so I really don’t want to add another toolkit to the mix there.  What the tocjs plugin does is to make use of the intergrator step to insert some custom Ant targets into the main build files, defining a new transtype called “tocjs”.  The downside to this, is that you have to run the transform process twice -once to generate the topic html files, and a second time to generate the ToC file(s).  It also annoys me that you have to update the base build files – it just seems wrong that a plugin should change files in its ‘host’.

So, I started digging around in the XSL transform files and the Ant build files.  It took a while, as there is not much documentation on them, at least not much when compared to the number of files and targets defined.  Eventually I found that the dita-ot/build_dita2xhtml.xml file defines a target named “dita.map.xhtml.toc” which is what calls the XSL transform to create the ToC.  However, there are no extension points for this.

I looked at the *_template.xsl files; however I didn’t feel like digging through the DOST code to find out what it would take to define a new XSL extension point.  Maybe its really easy.  Even if it is, it would require changing core files, and possibly interfering with any upgrade path.  If it is really easy, someone let me know, I could probably create the template file and send it as a patch. I did find one important bit of information which might help you even if you don’t ready past this point. There is a args.xhtml.toc.class parameter that you can pass into the standard transform to assign a CSS Class to the body element of the ToC. I have added this to the DITA Wiki, hopefully this helps out someone.

So, I am now thinking how to wire this all together.  The good news is it is possible, the bad is that altering the core build xml (and xsl) is simply the way the current integrator works.  The approach I took uses Ant import (not XSL import) to “override” the base “dita.map.xhtml.toc” with my own target, which is basically a copy of the base that points to a different XSL file.  Once I get the files in a little more advanced state I will probably release them as open source, although from what I can see if someone wanted to changed the main XSL file dita2htmlmap.xsl that wouldn’t be too difficult as well, and shouldn’t have any effect on existing code (other than adding a few extra @class declarations.

Step 1 : Create a plugin

Under dita-ot/plugins   (or demos if you prefer) create a new folder.  I named mine net.ipov.ditaot.toc.  In this folder add a plugin.xml file, you can copy an existing file and edit it too.  The plugin.xml should look like:

<plugin id="net.ipov.ditaot.toc">
 
    <!-- We want to dump the contents of the build_plugin.xml file into the main build.xml  -->
    <feature extension="dita.conductor.target.relative" value="build_plugin.xml" type="file" />
 
</plugin>

Step 2 : Create a copy of the XSL

I won’t include the full source here, as it is getting a little long.  But the basics are:

<xsl:stylesheet version="1.0"
    xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
    xmlns:saxon="http://icl.com/saxon"
    xmlns:xt="http://www.jclark.com/xt"
    xmlns:java="org.dita.dost.util.StringUtils"
    extension-element-prefixes="saxon xt"
    exclude-result-prefixes="java">
 
    <xsl:template match="/*[contains(@class, ' map/map ')]">
        <!-- change output of the top-level ul and add anything else you like. -->
    </xsl:template>
 
    <xsl:template
      match="*[contains(@class, ' map/topicref ')][not(@toc='no')][not(@processing-role='resource-only')]">
        <!-- change output of the li items in the ToC -->
    </xsl:template>
 
</xsl:stylesheet>

Step 3 : Add the build_plugin.xml file to declare the build target.

This is where you define the Ant target, which when pulled in by the integrator will override the built in target of the same name.  Note that this could possibly break in the future if the integrator changes the order of code to be before rather than after the imports (I think).  At first I couldn’t get both my override to work (it doesn’t work if the build_plugin.xml imports it) and get a file path that was relative to the plugin directory; however I stumbled on the answer in the dita-ot Yahoo Group while looking for some other information (on code highlighting). A little further experimentation and I was able to get somethign that worked.

First create a build file, must match the name declared in the plugin.xml, so here it’s called build_plugin.xml

<project>
 
  <import file="build_toc.xml"/>
 
  <target name="dita.out.map.xhtml.toc"
        unless="noMap" if="inner.transform"
        description="Build HTML TOC file,which will adjust the directory">
 
      <!-- define your own xsl, note you have to specify the ./plugins/NAME_OF_PLUGIN/ path here -->
      <xslt
       style="${xtoc_plugin.dir}${file.separator}xsl${file.separator}xhtmtoc.xsl"
       ... >
          ...
      </xslt>    
 
  </target>
 
</project>

Now we need a second build file, the build_toc.xml referenced in the first:

<project name="xtoc_plugin" basedir=".">
	<dirname property="xtoc_plugin.dir" file="${ant.file.xtoc_plugin}"/>
</project>

When the build_plugin.xml is merged into the core build files, the import is also copied in, with a corrected path. Then the path the plugin is captured in the imported build_toc file, which can be used in the ‘included’ target. Kind of tricky, and it feels a little “hacky” to me, but it seems to be working.

• Improvements to Commenting, including the addition of “Sort by Video Timing” to sort the comments based on the time on a video that the comment is associated with (applies only to video files).
• Visual formatting tweaks, including decreasing unneeded space between item previews in the “Grid” folder view mode, this greatly improves the layout for users with a 1024 x 768 screen.
• Addition of item flags for “Has comments”, “New Item”, “Changed Item” to help visually scan a folder contents.
• Further improvements to the upload control:
  • Addition of a “Keep Alive” using a Javascript timeout to keep the user’s session alive when on the upload page.  We’ve had issues with users going to the upload page, getting distracted and moving to some other application / task, then returning to the still loaded upload page and attempting to upload files, only to get an error when the (often large) file finishes uploading and the server fails to process it due to the user’s browser session being timed out due to inactivity.  This change will fix this.  The “keep alive” is also triggered immediately before running an upload which should cause most other errors to be detected before a user actually has to wait for a file upload.
  • Errors are now hidden by default, clicking on the “Errors” link in the upload status bar loads the list of upload errors; each error in this list is now cross linked to an online help page (http://www.ipov.net/apps/ccs-support/articles/cosolvent-upload-errors/) which explains the error in more details (and which can be updated faster than the application text).
  • Grid used to display files that are queued for upload has some visual improvements to make it more usable.
• Continued to work on updating the PHP code to run properly on PHP 5.3

The complete list of issues addresses can be seen at https://www.assembla.com/spaces/cosolvent/milestones/240821-milestone-27

Additionally, this release should mark the last development done in our SVN repository; we are transitioning to use of git to take advantage of its cheap branches and other distributed features.

The following scenarios illustrate situations where video-embedded documents might be handy and you can review the options in a lot more detail in this extended whitepaper.

• Large company IT departments are pushing employees to store their business documents in secure document management systems like SharePoint or Lotus Notes. These systems enforce enhanced security and offer document control safeguards that are difficult to replicate on standard web servers. Documents with embedded video coexist very nicely with these systems.
• For security reasons, the same IT departments may resist the proliferation of intranet or extranet web server applications. Even if a document could be hosted on a web server, policy restrictions or resource costs may make that difficult for people in business units and non-IT departments. Those individuals can author video-enhanced PDF or DOC files without requiring any special IT support.
• Although this problem is diminishing, companies with highly mobile workforces may still have people operating in places where web connectivity is marginal or nonexistent. Field service crews, overseas offices in developing economies and personnel co-located behind strict client firewalls may not be able to reach key company websites. They can carry a library of video-enabled documents on a hard disk, thumb drive, or CD.
• Most employees in large organizations use Microsoft Word and it would be convenient if all forms of publishing could be done with that tool. However, to work with other programs, Word documents often must be exported to another format. If you add video into the mix, that gets very complicated. One iPOV client found that, by converting Word originals to PDFs and embedding video, the resulting documents became much more universal. A given PDF document with embedded video can be stored in SharePoint, loaded into the Learning Management System, linked and made viewable online at a website, or emailed to parties outside the company.  One file, many uses.
• A similar situation occurred in a global multinational. Divisions around the world each had their own Learning Management System, some of which were old and not standards-compliant. If they published eLearning in the customary SCORM or AICC packaging it would have taken a lot of effort to import it into all of the varied, regional servers. However, every LMS (even the old and non-standard ones) could import and display a PDF. By packaging the video inside the PDF, the courseware effectively became a universal commodity.

Examples

(click on the images and captions to view PDFs with embedded video at iPOV’s website)

You can view more examples at iPOV’s website: http://www.ipov.net/content/rich-media-pdf

Gotchas

A fast-moving technology always generates surprises that initially baffle newcomers. These are the surprising limitations and gotchas that dictate what is actually possible. Accordingly, we begin this guide with a list of the key constraints that we have learned to work around:

1. Can I put a video into a Word Document and have it viewable and playable on the Page?
   No. You can create that impression if you insert a Windows Media ‘object’ into your document, but the video won’t actually be inside the Word file. It will be an external file that the document is linked to, and you must manage this linkage yourself. You can put a movie inside the Word file, but it will appear as a small icon that you must click to open. It is theoretically possible that a skilled programmer can write a macro or plugin to make this possible, but iPOV has not seen any developer activity in this area.
2. Can I put a video into a Word document and then save it as a PDF?
   Not reliably or well. iPOV is not aware of any tool that will reliably export a video-embedded Word document to PDF and have the video play correctly. First, if the video is in a typical, common movie format (MP4, AVI, WMV, MOV, etc.), it should first be converted into a Flash movie – something PDF exporting software won’t do.[1] Second, if the movie embedded in the Word document is already a Flash movie, the resulting embedded movie will have very limited play control (see point #3).
3. Can I add a Flash video to a PDF using Acrobat Pro?
   You can add a FLV or H.264 video or SWF animation easily enough, but the Flash Player doesn’t supply any play controls (start, stop, pause, tracker bar, volume, etc.). This is a big drawback in business situations where the viewer may want to review a key point or adjust the sound volume. To get good play controls, it is necessary to package the video and play controls together into an SWF file (e.g., using an external editor such as Adobe Flash) and insert the unified SWF file into the PDF.[2]
4. Why haven’t I seen more PDFs with embedded video – it looks really cool?
   Acrobat has supported embedding videos since version 6. The problem for business documents comes down to workflow – see answer #2 above.  In general if you want to edit the text of a document you will do so in Word and then re-publish it to a PDF.  At this point someone must individually re-insert all the videos from the old PDF into the new PDF. iPOV has developed a set of processes and procedures to help us do this quickly and correctly and we are working on tools to automate the process even more.[3]^{,    [4]}
5. Why not put the videos on YouTube and link them to a document?
   YouTube (and most sites like it) caters to people who want wide public distribution for their files. It has a very basic security system and it may be often blocked by corporate firewalls. Sites like these also tend to display ads that may or may not fit with your corporate image.

[2] The latest version of Acrobat Pro has an alternative way to import linked files, but it is finicky and prone to error. It is also more difficult to debug any broken links once the files have been imported.

[3] When documents are designed for large numbers of end users, it is often easier link to a video on a web server rather than distribute a packaged document.

[4] Note also that recent security changes have made some old documents no longer playable.

“We are trying to get traction for it as a service for what I believe to be a very badly underserved userspace: the no-man’s-land between people inside a corporate firewall and a closed community of stakeholders.”

Tony’s response, quite rightly, was to question my sanity. Of course, he was very polite about it:

“On the community side of things – I guess I’m surprised you say it’s underserved. My impression is there are lots of solutions, e.g., Ning.”

Umm. Yes.  Tony’s right. There are lots of solutions. I’ve had active accounts on Ning for at least 18 months and I went through the feature checklist. Technically, Ning will do most of the things that our CoSolvent Community Server can do, plus quite a few more. Other social networking tools are similar. Does that mean we’ve wasted two years on CoSolvent’s evolution? After a short recovery period, I realized that we developed CoSolvent around a set of assumptions and design concepts that we have not fully articulated – possibly even to ourselves. Now seems as good a time as any to set the record straight.

We designed CoSolvent Community Server (CCS) for business-oriented networking and video-sharing:

• We adopted a Windows folder operating metaphor that was as simple as possible so busy professionals could learn to use it.
• We designed CCS to operate with minimal hardware and software support because business networks need to reach all of the relevant stakeholders.
• We installed a rich underpinning of access controls, permissions and utilities so CCS can be molded to make workflows fluid and easy.

In many ways, CCS is like a box of Lego. The building blocks are individually simple, but they can be re-arranged to support a variety of practical business workflows.

What sort of ‘work’ network are we talking about?

We developed CoSolvent because we couldn’t find a reliable way move rich media (typically video) to and from the individual subject matter experts (SMEs) and managers among our various corporate training clients. Many of our corporate counterparts are not high-skill IT managers or experienced media folks. They are department managers, plant engineers, technicians and HR managers in big, security-conscious companies. They don’t have super-duper IT administrator privileges. They sometimes can’t even view YouTube. Yet, they’re the subject matter experts that we needed to share stuff with.

Our network collaborators are not really friends or social acquaintances. They are buyers and we are the vendor. It’s not about being social, its about the work. The work is the center of our network universe.

We needed a pragmatic tool for ‘work’ networking, not an engaging site for a ‘social’ networking.

Of course, if an existing social networking tool could double as a reasonable ‘work networking’ platform, we could avoid reinventing the wheel. If we could make Facebook or Ning, etc. do the job, that would be good enough. Unfortunately, there were a number of issues that gave us pause:

• The companies that employ our target audience strongly discourage employees from putting company assets on ‘public’ sites. If we wanted to use a Ning, we would have to convince their employer that it was safe. If we don’t control it and our client doesn’t control it, that’s a really tough sell to corporate IT.
• Workers often didn’t want their co-workers to see their materials until they had a chance to approve them. Can you put a video in Ning and ensure that only chosen co-workers (out of the larger community) can see it? Probably. Can you teach an IT-challenged manager how to do it and be sure that they won’t make a mistake? Can you make them feel confident that they won’t make a mistake? Not so easy.
• People often work with collections of related, but dissimilar materials. Most projects involve some video, some supporting text documents, possibly some audio files, some spreadsheets, etc. How could we keep those together and manage them in an orderly fashion in Ning or Facebook? We might do OK with Google Docs, but what about commenting and video handling?
• We wanted to accommodate all types of video as input. For example, there are scenarios where it is really convenient if our correspondents can upload and view SWF files. For security reasons, Ning, Facebook and Youtube will never let that happen because Flash animations can contain actionscript.
• It is hard to guarantee 100% access to a public social networking site – especially with IT-challenged users. The sponsors of Facebook or Ning don’t need 100% individual access for their sites to be successful. They engineer their software to make it as easy as possible, but ultimately they won’t care if a specific individual has an archaic browser or a vicious spam filter. However, if you want to network real work, 100% access is critical. If an individual can’t use the system, you must still do business. You will have to set up costly workarounds that can wipe out all of the productivity gains that the networking tool might offer.

If I try to frame our view of the contrasting demands in a diagrammatic form, it would look something like this:

A Social Network User participation is voluntary. People join because they gain something on an individual level – possibly for their career, but ultimately for their personal benefit. If, for any reason, a given individual user cannot fully participate, the server’s Sponsor may care – but not too much.	A Work Network A commercial Sponsor wants a safe, virtual space where all business stakeholders can participate – to do their job. A  ‘stakeholder community’ (e.g., a supply chain, an association, or a school) can span many individuals and organizations across the public Internet.

But the biggest problem:

A lot of real-world business ‘workflow’ isn’t person-centric.

Social networking tools are designed around the individual user. A user typically logs into ‘My Page’. From there, the user can engage other individuals, join groups of other individuals and share media with other individuals. They can form new clubs and groups with other individuals. However, at the end of the day, the individual is still the center of the universe.

Business interactions are often not about the individual. They may be more naturally expressed as company-to-company, department-to-company, project-to-consultant, or buyer-to-seller interactions. In fact, there can be any number of different central actors, some human and some organizational, in a working business network. Sure, you could start everything from the individual and build the structures for the other entities, but that is just the long way round. Why not establish a Lego-like structure that can be reconfigured to support the workflow directly?

There are lots of other issues and considerations, but we decided that we were looking at a problem that wasn’t really social. It was more pragmatic and utilitarian and commercial. We looked at a lot of possible solutions and finally decided to roll our own. We developed CoSolvent Community Server. There is a thorough technical description elsewhere on our website. However, Tony’s question reveals that our market positioning explanations are still not clear or adequate. So, until we can remedy the main site, let me try to summarize and clarify the concept of CCS:

• CCS is a web-based file sharing tool with a suite of extra features. Folders can be labeled anything the user wants. Any ‘social’ tools are slaved to the folder metaphor. For example, groups are formed by giving them defined permissions and their own folder structure.
• The Windows folder metaphor is easily customized to fit a wide variety of access schemes and workflows. The goal is flexibility and simplicity. We want to fully streamline the average worker’s collaborative experience – without adding extra navigation and structural complexity.
• It is designed to be maximally accessible by a wide range of users.  CCS works with minimal client-side requirements: low to modest bandwidth, web browser, and Flash. It has proven adept at reaching behind firewalls, to users  with Macs, to workers in other countries, etc. While CCS makes it easier, achieving 100% access will ultimately depend on the willingness of stakeholders, technical people, iPOV and community developers to work together.
• It is optimized for the exchange of video materials. The potential of video as a day-to-day business communication tool has barely been tapped. In the wild, video clips exist in a dizzying array of types and it is hard to share them without performing conversions and extra processing steps that most people don’t want to learn. CCS directly supports a wide variety of video types.
• It is designed to be quickly set up and hosted on a vanilla installations. Currently, all of our working installations are in Amazon’s EC2 electronic cloud. We can set up a new, totally dedicated, site in minutes, while piggy-backing on Amazon’s security infrastructure.

Another way to grasp the difference between CSS and a  typical social network is to look at some practical application scenarios.

Target Applications – Camera Based

Small, inexpensive, easy-to-use solid-state cameras burst on the scene 3 or 4 years ago. Examples include the Flip camera, the RCA SmallWonder, the Sanyo Xacti series and the Kodak Zi series, along with many, many, many others. That doesn’t even count the increasingly ubiquitous mobile phone camera.  Surely there ought to be a way to apply these new tools in day-to-day business operations.

Scenario 1 – Confidential Quality Review

A corporate quality manager (CQM) uses CCS to get video reports of defects and problems from far-flung plants. Security is crucial. The CQM doesn’t want anyone (not even his VP) to see the videos before he has a chance to review and assess them. At the plant level, only the plant quality manager (PQM) is allowed to record and upload this type of video. We  can set up a folder arrangement in CCS as shown in the following diagram:

1. The PQM for Plant #5  makes a video (or possibly a still photo) of the problem. The PQM places the media in a special ‘defect report’ folder  that is visible only to the PQM
2. The ‘defect report’ folder is actually just a link to a real folder for Plant #5 that resides within the corporate quality area. That folder is visible only to the PQM and the CQM.
3. When the file arrives in the CQM’s Plant #5 folder, the CQM receives an automatic email notification that a defect report has arrived from Plant #5.

The CQM can take several actions. He/she can phone the Plant #5 PQM and discuss the problem. Having the video as a common talking point will likely speed discussion and resolution. The CQM can move the video file out of the hidden folder to the general area – possibly into a folder of known issues. If the CQM adds a comment with suggested remedies (or records and uploads a video), there is now a permanent record of the problem and the fix.

Scenario 2 – Getting Action from a Supplier

The receiving manager gets a shipment that is badly packaged. If he spends the next few days on the phone, he might get the supplier’s attention. CCS may be able to elicit a better response – if we set up folders so he can easily send a video to the supplier. One possible structure is illustrated in the following diagram:

1. The receiving manager spots a problem with the way a shipment is packaged. He/she records a short video to demonstrate and document the problem and uploads it to Supplier A’s ‘public folder’ on the CCS. The public folder is a special type of folder (designated with a yellow icon) that doesn’t require a login for any of the items that it contains.
2. The supervisor at Supplier A receives an email with a link to the video in the public folder. The supervisor just clicks the link to view the video.
3. The receiving manager follows up with a phone call to discuss the problem. Since both parties have viewed the video of the problem shipment, the issue is resolved quickly and decisively.

The ‘public’ folder is the key to this scenario. It allows the receiving manager to send the video safely without requiring that the supplier be registered in the system. The CCS public folder system is smart enough to only allow the viewer to see a) the item at the link they were given, or b) if they were given a link to a folder, they can see any items and subfolders that the linked folder contains. By giving the folder a distinctive (yellow) label, CCS makes it easy for occasional users to know where files are public and where they are private.

• You can view a ‘made-up’ example in this folder on our demo CCS.

Target Applications – Screencasting Based

CCS can be used with free software tools to rapidly generate document and media reviews. The tools we use most often are the following:

• BB Flashback Express – a free screencast recording program
• DemoHelper – a free program that draws on top of everything on the computer desktop (except that it automatically pauses running movies when you try to draw or write)

The basic idea behind the following examples is to make a screencast movie as you view and comment on documents or media in the CCS – then upload the movie of your commentary to CCS as a permanent record. With a little practice, this is much faster than trying to craft written comments – and typically much clearer.

Scenario 3 – Near-painless Media Review

We needed to get clients’ reviews of our work-in-process eLearning media. Client staff are busy and too-often unavailable. Plus they reside in a different city, so meetings are a chore. We can set up a folder structure with ‘Drop off’, ‘Review’, and ‘PickUp’ subfolders and show our clients how to use a free tool, BB Flashback Express, to record their comments. Now the review process goes like this:

1. We place the material for review in the client’s folder in the CCS.
2. We email the SME a link to the material that is up for review (or they get an automatic email notification if they have subscribed to the folder).
3. The SME starts BB Flashback Express to make a screencast of their review.
   • The reviewer opens the link to the viewable media and starts to watch.
   • Whenever they see something of note, they can pause the media, use their mouse to point out the feature and add a verbal commentary.
   • When they have finished their review, they can add any general comments, or cycle back through the media to add second thoughts.
4. The SME saves their screencast as a Flash file and upload it to CCS beside the media that was reviewed. They don’t even have to export their comments as Flash. They can just upload the raw BB Flashback file and we will replay it on our end. If there are any written materials (e.g., supplementary documents or comments), they can upload them or write them in the same folder as the reviewed material.

That’s it. We are finding that our clients can often review a 20 minute eLearning lesson in about half an hour. It takes us a bit longer to listen to their review, but there is seldom any confusion about their request. That means that our overall time investment is reduced. Win-Win.

Scenario 4 – Lightning Fast Essay Grading

I and several of my staff are currently teaching or have recently taught university-level courses where we had to grade student papers. Oh boy is that fun. However, we are trying a new approach. CCS can be configured so each registered user (aka student) gets their own private folder – just like any social networking tool:

1. We ask students to submit their papers as PDFs so we can view them directly online in CCS.
2. We automatically get an email when each file arrives.
3. We use BB Flashback and Demohelper to mark up the paper and record our verbal comments.
4. When we finish, we save the movie as an SWF and upload it into the student’s private folder beside their essay.

If the student followed our advice and ‘subscribed’ to their folder, they will receive an automatic email as soon as our comment video file has finished uploading. We can even log in with different browsers and upload a video in the background while we record the next video in the foreground. If we want to add text, say to suggest a rephrasing, we can cut, paste and edit text from the PDF to the CCS commenting utility. Bottom line, we can read, comment and grade an essay in just slightly longer than it would normally take to simply read the paper version. With 30, 50 or 60 students in a class, we like that idea. It gives a much better audit trail and, considering my atrocious chicken-scratch handwriting, the students probably learn more.

Scenario 5 – Commissioning Graphics at a Distance

We get our graphics done by a variety of designers. Some are local. Some work half a world away. However, iPOV often needs graphics done the same day or overnight. How can we do that with a designer in, say, Russia? An iPOV staff member typically records a short video to explain what they need. The camera arrangement is simple and cheap (under $250):

With this crude rig, we can record a 5-7 minute video to explain what we want. Even though we may be abysmal artists, we can make stick-figure drawings and explain our intent and requirements as we go. In a video, we can give far more context and rationale than we would ever have the patience  to put in a written specification. After the artist uploads a draft, we can comment in CCS. Sometimes we use BB Flashback Express and/or Demohelper to make a short screencast movie of our verbal comments – using the mouse as a pointer. That way the artist knows exactly which feature we are talking about. We can go back and forth several times in a day, although usually one or two cycles with the video comments are sufficient.

• You can view the sequence of a typical design process laid out in this folder on our CCS Demo site.

Summary

We designed CoSolvent Community Server for business-oriented networking and video-sharing. We adopted a Windows folder operating metaphor to make it as familiar as possible to the busy professionals that must learn to use it. We designed CCS to operate with minimal hardware and software support because business networks need to reach all of the relevant stakeholders. Finally, we added a rich underpinning of access controls, permissions and utilities so that we can mold CCS to make the workflows fluid and easy – especially for the tasks that make or save money for the sponsoring organization. In some ways, CCS is similar to a box of Lego. The building blocks are individually simple, but they can be re-arranged to support a variety of practical business workflows.

It’s possible that someone could customize Ning, or HiveLive, or SharePoint, or Google Docs, or … to work like CCS. However, we don’t think these tools were conceived for that purpose and it seems like it would be a force fit. I’m sure that others will pick up on the CCS idea and address this application space. Until then, we believe that our target market is still a bit ‘underserved’.

Before getting into my solution, I’ll mention the two modules that are closest to what I want to achieve:

1. Galleria – this module produces a carousel-style listing of image thumbnails, when a thumbnail is clicked on the full-size image is shown. However, this module has the following problems for my use case:
   1. The thumbnails are simply the original image file with an explicit width and height set; this means that if you have a lot of them, it can take quite a while for them all to load.
   2. Loading is not actually asynchronous, but there is a significant delay while the javascript initializes during which the content is hidden. There is no progress indicator during this time.
   3. The admin panel for the module has very limited options – the worst is that it doesn’t let you set the size of the carousel (which can be overridden in CSS), but does ask you to specify how many images to display – the images are scaled (using CSS) to fit in the carousel’s default size (you can hack the JS code to fix this, but then have to reset a number of other CSS properties).
2. Fancy Slide - this module seems to be very new and as such has pretty much no documentation. If its development continues it could become a viable alternative to my needs. The biggest problem with this module currently is lack of control over the presentation.

The following solution uses existing modules. It seems logical that this technique is already out there, but as I can’t find it documented, I’m doing that here. The main modules you’ll need:

• ImageAPI
• ImageCache
• CCK, CCK Filefield, CCK Imagefield
• Views
• Thickbox - for some reason the latest version of the Lightbox2 module is creating JS errors when mixed with the lastest JQuery version.

After installing the modules listed above here’s what you do:

At this point you probably want to create one or two Screenshot nodes so that you have something to look at while building the view. Go to “Create content” > Screenshot. Enter the Node Title. Scroll down to the “Screenshot” field and upload an image file; once it has uploaded you should get a “Title” field next to the file where you can enter a description (note that entering HTML here probably won’t work too well as the contents of this field are output as an attribute).

Now for the final part: creating a View. Go to Admin > Site building > Views and “Add.” Use the settings:

That’s it. You can see our screenshots page at http://www.ipov.net/content/cosolvent-screenshots-0

If I have time I’ll also setup a quick screencast and update this post with a link to it.

• You want to do Flash work that is mostly development oriented. The environment described here will be useful for a programmer or small team using supplements from a designer as opposed to a designer working in the Flash IDE with supplements from a programmer.
• You want a command line interface and a tool chain that can work easily with existing continuous integration and web deployment tools.

The following steps will take you through the required set up for a sample project. There is a link to the full source at the end.

Step 1: Download the Flex SDK

Adobe’s open source Flex SDK provides, among other things, an Actionscript compiler binary: mxmlc. It’s not just useful for compiling mxml based Flex applications however; it can also be used to compile lightweight, pure Actionscript 3 projects. The download will consist of a single zip file which you may extract to a directory of your choice. On windows, I choose c:\flex, and on linux I choose /usr/local/share/adobe-flex/sdk. You’ll just need to remember the path when you set up your build environment. Note that for the compiler to work, you’ll need to have Java 1.6+ installed.

Step 2: Download the Flash debugger standalone player and plugins

Ok, so this part isn’t open source, but you can’t have Flash these days without Adobe’s Flash player. The debug flash player will conveniently display a stack trace whenever there’s an error. The trace will even include line numbers if you build your swfs with the debug flag, which you will see how to do below. The debug enabled browser plugins are installed in the same manner as the normal browser plugins. If you’re running Windows, installing the ActiveX control will result in having a debug enabled player in IE. On both Linux and Windows, installing the ‘Plugin content debugger’ will give you a debug enabled player in browsers like Firefox and Chrome. The standalone player can be placed anywhere. On Linux I’ve copied the flashplayer executable to /usr/local/bin, which is on my PATH.

Step 3: Install Ant and the Flex SDK Ant tasks

Since the Flex SDK internals are predominately written in Java, Ant is used as the build tool of choice for most Flex and Actionscript 3 projects. Accordingly, Adobe provides a set of Ant tasks for invoking various SDK related commands from within Ant. First install Ant (if you’re on a Linux system, you’re better off using your distribution’s package manager rather than Apache’s packages). Copy the file flexTasks.jar from <flex sdk path>/ant/lib to your Ant installation’s lib folder. On my Ubuntu Jaunty system for example, it was /usr/share/ant/lib. You will also copy from the flex Ant folder the file flexTasks.tasks to your project folder once it is created.

Step 4: Choosing an editor/IDE

Now that you can compile Actionscript files and view the results, you’ll need to select an Actionscript aware editor or IDE. If you are using Vim, there are a number of syntax files around the web. I’ve had luck with the ones found on Adbul Qabiz’s blog for example. On Emacs, you will find what you need on the Emacs Wiki, including some FlyMake code (build as you type). If you are running Windows, there is a tailored open source solution available: FlashDevelop. FlashDevelop provides IDE functionality for Actionscript 2 and 3, Flex, Air, and haXe. If you’re accustomed to Eclipse, Visual Studio, NetBeans, etc., you should feel right at home with FlashDevelop.

Step 5: Creating a project template

The main aim here is to build your project by issuing one command from the command line. You’ll start by creating a project folder, and inside the project folder you will create a file called build.xml for use with Ant. If you intend to collaborate with others on the project, it’s also a good idea to separate system specific variables into another file. At iPOV, we use a separate file called build-user.properties. Here are samples of both files:

<project name="miniplayer" default="build-all" basedir=".">
    <description>
           Builds iPOV Hello World
        To use, :
          1. Copy %flex_sdk_3%/ant/lib/flexTasks.jar  to %ANT_HOME%/lib
          2. Copy build-user.properties.default to build-user.properties
            (so it doesn't get commited to SVN) and
            edit the paths for your install.
          3. Invoke the build ">ant [build-target-name]" (either via commandline of GUI launcher)
    </description>

    <!-- Import the property definitions. -->
    <property file="build-user.properties" />
    <property name="PROJECT_NAME" value="ipov_hello-world"/>
    <property name="PROJECT_VERSION" value="1.0.0"/>
    <property name="DEPLOY_DIR" value="bin"/>
    <property name="MAIN_CLASS" value="src/net/ipov/hello_world/Main.as"/>

    <taskdef resource="flexTasks.tasks" classpath="${TASK_HOME}/flexTasks.jar" />

    <target name="build-all" depends="build-swf,build-debug-swf"/>

    <target name="build-swf" depends="init">
        <mxmlc file="${MAIN_CLASS}"
            output="${DEPLOY_DIR}/${PROJECT_NAME}-${PROJECT_VERSION}.swf"
            debug="false" optimize="true" fork="true"
            default-background-color="0xffffff" >
            <source-path path-element="src/" />
        </mxmlc>
    </target>

    <target name="build-debug-swf" depends="init">
        <mxmlc file="${MAIN_CLASS}"
            output="${DEPLOY_DIR}/${PROJECT_NAME}-${PROJECT_VERSION}.swf"
            debug="true" optimize="false" fork="true"
            default-background-color="0xffffff" >
            <source-path path-element="src/" />
        </mxmlc>
    </target>

    <target name="init">
        <mkdir dir="${DEPLOY_DIR}"/>
    </target>

</project> 

#
# Copy this file to .user.properties and then edit it to match your system
#
FLEX_HOME=c:/flex3/sdk
TASK_HOME=c:/bin/apache-ant-1.7.1/lib

Replace ipov_hello-world above with your project name, and replace the net/ipov path with the namespace you will use for your main source files.

If you are using FlashDevelop, you will now create a new AS3 project using Project -> New Project. For Location, browse to your project folder where you have placed the two files above. For Package, type your primary namespace (net.ipov.hello_world in this example). FlashDevelop will create the necessary files and folders for you. Outside of FlashDevelop, you can simply create a folder called src, and inside place folders corresponding to your primary namespace. Then create a file called Main.as inside your primary namespace folder to act as the entry point for your application. Here the content of Main.as in the Hello, World! sample:

package net.ipov.hello_world
{
    import flash.display.Sprite;
    import flash.events.Event;
    import flash.text.TextField;

    [SWF(height='300', width='400')]
    public class Main extends Sprite {

        private var _params:Object;

        public function Main():void {
            _params = root.loaderInfo.parameters ? root.loaderInfo.parameters : new Object();

            if (stage) init();
            else addEventListener(Event.ADDED_TO_STAGE, init);

        }

        private function init(e:Event = null):void {
            removeEventListener(Event.ADDED_TO_STAGE, init);
            // entry point
            var helloText:TextField = new TextField();
            helloText.text = "Hello, World!";
            stage.addChild(helloText);
        }

    }

}

Once you have set up your project folder, invoke the following commands from the root of the project to build and launch the application:

~/projects/as3-hello-world $ ant
Buildfile: build.xml

init:

build-swf:
    [mxmlc] Loading configuration file /usr/local/share/adobe-flex/sdk/frameworks/flex-config.xml
    [mxmlc] /home/joseph/projects/as3-hello-world/build/ipov_hello-world-1.0.0.swf (833 bytes)

build-debug-swf:
    [mxmlc] Loading configuration file /usr/local/share/adobe-flex/sdk/frameworks/flex-config.xml
    [mxmlc] /home/joseph/projects/as3-hello-world/build/ipov_hello-world-1.0.0.swf (1021 bytes)

build-all:

BUILD SUCCESSFUL
Total time: 9 seconds
~/projects/as3-hello-world $ flashplayer build/ipov_hello-world-1.0.0.swf

If you are using FlashDevelop, you can also use Project -> Test Movie (F5 on the keyboard). When prompted to configure the compiler, set your Flex SDK location under AS3Context, and set the standalone Flash player location under FlashViewer.

That should be enough to get started developing AS3 applications. Future articles will include information about unit testing, continuous integration, deployment, and Adobe Captivate Widget development.

as3-hello-world-source

If not, check out the ATEN CS228.

The ATEN CS228 is a KVM Matrix switch with the following properties:

• It can control up to 8 computers (or 64 computers if it is daisy-chained).
• Two consoles can access shared computers simultaneously.
• It has audio (speaker/microphone) support to/from both consoles.

In plain English, this means that two operators can share up to 8 computers at a time and follow several collaboration modes:

1. They can share a single computer – one operator has full control while the other is a passive observer.
2. They can switch computers in seconds – as long as they don’t try to use the same device (in which case, see scenario 1)
3. They can pass control of a given device back and forth between them with a few keystrokes.

Consider the scenario where you need to train a new hire to use a complex software package (e.g., CAD, business intelligence, movie editor, etc.).

The idea is simple. Pair a newbie with an experienced professional and give the newbie some introductory tasks. Even the simple tasks will have a few tricky parts. That’s when the newbie calls across the cubicle and asks “How do I do this?” The mentoring professional hits a couple of keys to take control and demonstrate – while the newbie gets to watch and ask questions. A quick demonstration and it’s back to work for both of them. As the newbie gains confidence, the mentor can share more complex tasks – first by letting the newbie watch, then by letting the newbie drive under the mentor’s watchful eye. Eventually, the questions will subside and both will be working full time on value-added tasks.

The following figure shows how this compares with standard classroom and OJT. The intensity of blue in the diagram indicates the amount of revenue work that is being done. Dark blue is all productive work. Light blue is semi-useful. White is purely overhead devoted to teaching and learning.

You’ve seen multimedia that you would love to use in corporate communication. Unfortunately, the corporate IT department is very security-conscious. They resist installing a new server or web application inside the firewall, and they forbid putting corporate information on outside hosts. They ‘encourage’ everyone use the company’s secure document management system (.e.g., Lotus Notes or Microsoft Sharepoint) for all business communication. Is video out of the question?

iPOV’s Rich Media PDF

iPOV has refined a way to embed sophisticated, animated Flash videos inside a standard Adobe PDF file. The result is an integrated, thoroughly standard PDF. If you give us a Word document and a video (in almost any format), we will return a polished ‘Rich Media PDF’ like the following examples. Note: In keeping with their PDF format, these should be downloaded to a local disk and viewed from there. Download times will vary according to file size:

Right Click on Thumbnail and Save PDF to Disk in Order to View	Example Application
	Software Instruction Memo (1.7MB, 1 video clip) – It’s pretty common that a minor software problem will get in the way of productivity. Wouldn’t it be nice to record a quick fix or procedure change and send a totally unambiguous memo to let everyone know what to do.
	Video work instruction (2.2MB, 2 video clips)- This shows the correct method to perform the sort of factory or distribution task that is used throughout industry. The work instruction design contains two video clips. One shows the task being performed at full, expert speed. The second shows it being performed step-by-step to make the subtleties more evident. Click here to view an in document version.
	A video prospectus for a real estate property (10MB, 1 video clip) – Most of the information in this flyer is given in the embedded video clip. Even though the video has no commentary, it still gives a more accurate impression of the property than any text or still picture could ever achieve.
	Instruction sheet for a computer maintenance task (1.9MB, 1 video clip)- This video-enhanced document combines a step-by-step written procedure with an illustrative video clip. The listing ensures that the viewer has a complete guide to the tasks. The video clip ensures that the viewer can put the list of instructions in their proper physical context.
	Procedure for using software (14MB, 5 video clips)- Video clips with screencast movies of a software application have been added to a detailed step-by-step procedure. The procedure provides the accurate details for the task, while the videos provide situational context and a sense of the flow of the transaction. A viewer can remember the transaction flow far more easily than they can memorize a list of steps.
	How to change the oil in your car (3.7MB, 1 video clip)- This is a simple procedure, but it illustrates how a synchronized script can be added to the video clip to make the speech clearer. The companion script could also be used to add extra description or even warnings that are synchronized with the action.

Who would need this?

These PDFs will play on any computer where Adobe Acrobat Reader and Adobe Flash Player are installed. Presumably, anyone who wants to view a PDF will have Acrobat Reader installed and, according to Adobe’s statistics, Flash Player is installed on 98% of computer desktops. Companies can handle situations where a multimedia web page is not feasible:

• IT security policies make it difficult to put the video on a web site.
• Bandwidth limitations make it difficult to stream video to the target audience.
• The target computer is not connected to a high-speed network.
• Users are carrying laptops into areas with low connectivity.
• The company’s official documents must reside in a document management system like Sharepoint or Lotus Notes.
• The company assembles collections of documents to distribute on CD or DVD to stakeholders beyond the firewall.
• The company deals extensively with overseas offices that have slow connections.
• etc.

In each of these situations, a Rich Media PDF would offer an attractive alternative. This format will fit in many of those awkward places where a multimedia website cannot reach.

Requirements, Time and Cost

• The cost depends on the amount of processing that iPOV must apply to the video. To prepare a video (without additional editing) and place it in a PDF with customer-supplied text (e.g., with the formatted contents of a Word document) typically costs $75/page, or less in larger quantities.
• If iPOV is asked to apply its standard video transformations to the video clips, the cost will generally be determined by the transformations. Since the ‘flattened Flash movie’ is an iPOV standard output, PDF page publication fees are typically waived.
• Simple page constructions are returned in 1 to 2 days.

Bottom Line

Rich Media PDFs are a useful compromise between static text and graphics documents on one hand and multimedia websites on the other. They offer rich multimedia, with a level of portability and flexibility that a website cannot match. Finally, they offer rich media in a package that is widely accepted by security-conscious IT departments. If you have text documents and videos that you would like to display together, consider giving us a call.

The Global Supply Chain Analogy

The problems that individuals and companies have in communicating with other languages and other lands are virtually the same challenges that have afflicted the shippers of goods throughout history. If you look at images of previous transportation systems, you will see that nothing really changed over most of human existence. Every shipment was pretty much handled the same way. Stuff was loaded and unloaded and loaded and unloaded. The ships got bigger and faster, trains replaced barges and wagons gave way to trucks, but it was always a laborious, error-prone system as shown in the following images:

Each individual box, bale and bag had to be handled separately, perhaps a dozen times between origin and destination. How many times did a package get lost? How many times was it misplaced? What if there was something valuable or time-sensitive in that package? Tough luck. Think airline bags – but this all changed with the advent of standard containers and specialized handling equipment:

Once pieces are loaded, locked and sealed in a container, they are never touched until they reach their destination. In between, the entire transportation system is optimized to move and store standard 10ft x10ft x 40ft boxes. To the transportation system, their contents are irrelevant. There are no bags to leak, no boxes to break and no bales to spill. Just a standard box that is handled the same efficient way in thousands of terminals and ports around the world.

How important is this innovation? Almost unmeasurable. If standard containers didn’t exist, it is doubtful that we would have anything like the current global economy. Walmart and Target could not exist in their current forms. Products in every part of the world would be more expensive and new innovations would arrive much later to the market. The immense choice that consumers enjoy would be greatly reduced. The quality of our goods would probably be lower. Things would not be the same.

The Traditional Knowledge Supply Chain

So how does the remaking of the global supply chain concern issues of knowledge, culture, language or eLearning? Consider the system by which we transmit technical knowledge across distance, culture and language:

This is also a supply chain – with the same problems that have afflicted goods transportation for millenia. This diagram might have described how a Greek trader communicated with a Roman merchant. Each idea is written, interpreted or translated multiple times, often with a poor understanding of the original context or nuance. It’s the pre-container goods shipping system applied to technical knowledge. By the time it reaches its destination, the message can be lost, garbled, de-emphasized or distorted – and the shipper may never know. If my technical instructions are translated into Arabic for someone in Morocco to act on them, how can I know that they are correctly conveyed or understood?

But what if we could find a standard shipping container for our ideas and knowledge. What if we could take our technical information, seal it in a box with standard ‘dimensions’ and send it through a communication system that is optimized to handle that package quickly and efficiently? What if we could track each shipment cheaply and easily? What if we could inspect the contents ourselves after it reaches the destination? Wouldn’t that be as revolutionary as global containerization?

A Shipping Container for Ideas?

As I described in this earlier article, iPOV believes that video offers special benefits to the communication of ideas across distance, culture and language. If we use video as part of the communication package, it can retain its integrity across the full communication sequence:

In other words, video is a standard shipping container for knowledge! Video can convey accurate information without words. You can see the power in this YouTube movie: Japanese instructions on how to peel a potato in 2 seconds. Even if you don’t speak Japanese, you can probably figure out how to copy their method. There are enough visual cues to remove most of the uncertainty. The words, if anything, just distract and get in the way. In the following examples, a video ‘how-to’ is delivered in three different language contexts. The video clip remains the same. Even though the accompanying text and commentary traverse the traditional translation process, the information contained in the video was packed and sealed when the video was made. The video portion will always convey the same message and will always act as a contextual check on the accompanying text and commentary. In fact, the text and commentary in this example represent little more than elaborate shipping labels. Try turning the sound off on your computer and watching the clips again.

Printer Maintenance (English)

Printer Maintenance (Chinese Subtitles)

Printer Maintenance (German)

This example makes a strong case for the “video as container” idea. There will be many other types of information that are not as easily packaged in an visual format as this physical procedure. Nonetheless, adding video to any communication will put some fraction of the total message into a package that will guaranteed the contents throughout the journey. Even if most of the message is more easily captured in text, an accompanying video clip will increase the odds that the recipient will put the message in context.

Most of the infrastructure and technology to efficiently handle video is already in place. Many tools exist on the public Internet (e.g., YouTube). Hosts of other tools are being developed by web companies, software vendors and in open source projects. For its part, iPOV has developed and assembled a uniquely comprehensive toolkit that is specifically tailored to speed and facilitate this process, including our Video Translation Transformation and our CoSolvent Community Server.

Bottom Line

I believe that our global economy is on the verge of an information revolution that will be as profound as the one that transformed goods transportation in the past 30 years. It will take a while for the opportunity to sink in, but gradually people will discover how much it will pay to explain things in a visual form. Adding an informal video to a technical communication will make it more likely that the message will get through and iPOV is aggressively developing the ‘virtual’ trucks, trains, ports and cranes to handle this new type of information cargo.