We made a couple decisions up-front, and one of them was to import the latest release code drops from OSMF into an internal git repository; that way if we ever need to make any patches we have the code right there, and anyway as with any open source project it can be very useful to go through the source code to understand how best to use it.  So that decision brought on the next, which was: do we go ahead and setup to build the osmf.swc library ourselves.  After debating this, we decided that it would provide useful experience.  Alas the OSMF SVN lacks a decent build script, seeming to rely on FlashBuilder.  Luckily the Strobe Media Player does have a basic set of ANT build scripts.  Now, I’ve been using ANT for quite some time, and everytime I have to use it on a new project I ask myself: isn’t there anything better?  So far the answer has been “no”.  So, I started working through an attempt to modularize the SMP build script.  I believe I managed to get something that was workable, while being fairly ugly; however along the way I decided that the build for CFP 2.0 should be cleaner if at all possible and decided to go though another search.

Of course one of the obvious tools for any Java developer such as myself has got to be Maven, although up until now I have avoided it, having found it approach too constrictive for my comfort, and that making the transition seems to involve an awful lot of new things to learn, which are not super well documented (not that most other open source tools are really much better).  We also have a (so far) internal tool built using the Eclipse RCP framework, and had also started to look at the e4 projects as the next logical step there; but again, the Eclipse build tooling always has struck me as incredibly non-user friendly.  The big problem we run into is that, because a number of tools that we want access to are part of various plugins (such as XML editing), we end up shipping a whole bunch of the IDE functionality, and that creates a huge set of dependencies to manage.  Now, if you have all day, you can simply re-provision them each time you need to build, downloading the latest stable releases, but that is not going to work for incremental builds.  So we are left with the question of managing a “target platform” full of modules (features and related plugins) that we want to keep up-to-date, and we don’t have a separate build developer.  One of the developments that caught our attention was the Tycho project, which seemed to address some of the issues, and since Tycho is built on top of Maven3 that seemed to provide some added incentive to consider moving to Maven.

Starting out with maven was somewhat ugly, as the maven way of doing things seems to be mostly derived from the process that a Java project might need, but we kept learning.  There is a “flex mojo” to add the ability to call mxmlc and compc from within a maven build as a semi-standard part of their lifecycle; however we quickly ran into a problem.  We need to control the version(s) of flex we are compiling with/against.  Apparently this used to be possibly, however after getting a few too many complaints from users who’d shot themselves in the foot with a path issue, the one guy who maintains the flex mojo basically decided to do his best to make this “impossible” for new users (see his discussion board postings).  In addition to creating technical problems, the attitude also raised a number of questions in our minds about if we really wanted to go that route.  In the end we decided that since the Tycho tool chain was not yet ready for us (or we weren’t ready for it), there was not really a compelling reason to use Maven.  So it was back to the drawing board.

After looking at numerous tools, I finally rediscovered Gradle.  I say rediscover because I’d previously seen it, when it was in a much less mature state.  Anyway, a quick google showed that not only would it be possible, due to Gradle’s built in support for ANT tasks, to use the Adobe mxmlc and compc tasks, but that just recently work had started on a plugin for adding even better support for Flex development into Gradle as a plugin – GradleFx

So, I started working on a test of using gradle to compile the OSMF code and plugins.  At this point, as I’d anticipated, I managed to run into a number of beginner issues; however I have been able to work my way through them, with the kind help of input from the GradleFx developers.  One thing I’ll note here is that you can avoid having to “install” the GradleFx plugin into a local maven cache by simply putting it in a local folder and declaring that as a “flat repo” like:

1
2
3
4
5
6
7
8

buildscript {
     repositories {
        flatDir name: 'localToolsRepository', dirs: "${buildTools}/lib"
    }
    dependencies {
        classpath group: 'org.gradlefx', name: 'gradlefx', version: '0.2.1.ipov', ext: 'jar'
    }
}

Note that the buildscript closure is evaluated right away, before the rest of the build, so if you want to use any variables, such as ${buildTools} in the example above, then you have to define them in a gradle.properties file.

I found that cloning the GradleFx repo enabled me to look over the code and get a better feel for what its doing, as the documentation is still a little light; however I soon found that I had a couple of ideas for some changes to the GradleFx code.  Since this is on GitHub, I decided to try my first ever GitHub hosted fork.  The process seems to have gone well, and so far I’ve been able to contribute a small change in the path handling.  I am currently working on code to add explicit includeSources and includeClasses properties to at least the compc code, as currently the compc implementation is using all the declared source-paths as include-sources too, which is going to work most of the time, but not all.  This should then mean you can reuse .flexLibProperties – something that the SMP build does, but much more simply.  I have the following as a part of a multi-project build (OSMF comes as several different components that I’m building separately):

120
121
122
123
124
125

def flexLibProperties = new XmlParser().parse( project.file('.flexLibProperties') );
def incClasses = [];
flexLibProperties.includeClasses.classEntry.each {
    incClasses.add( it.'@path' );
}
project.tasks.compile.includeClasses = incClasses

I am considering pushing my OSMF repo to GitHub, but my big hang up is that right now I am unsure how much TLC I’m going to be able to give it, and I don’t want to create any false expectations from others.  For instance, if it becomes clear that we’re not going to need to have the ability to build OSMF ourselves, then it would be much simpler to just use the latest binary.  However, in the mean time I intend to try and post a few other tips and try to contribute any other ideas I have to the GradleFx project.

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.

Additionally several bugs were fixed, you can see the complete issue list in Assembla at https://www.assembla.com/spaces/cosolvent/milestones/283241-milestone-32—video—pdf-improvements.

Additionally, PDFs are now opened with the site navigation menu minimized, giving the PDF approximately 200 more pixels horizontally.  We added a expand/collapse menu button which can be used to open the menu.  Other file types open with the menu auto expanded, although the user can collapse it.  Our next milestone should move this from a totally automatic behavior to something that administrative users can set in the file properties.

Other changes:

• We upgraded to using Dojo 1.5
• The look of the Comment section has been improved, and couple of behind the scenes tweaks made.
• In the Manage >Permissions, the dialog to select Users or Groups to assign permissions to can now be navigated via keyboard (arrow keys to next/back, or press a character to go to the next entry starting with that character).
• When re-uploading a file you can now choose to overwrite the existing title, description, and summary using new data.  Previously you had to re-upload and then go to “Edit Properties” to change this information.

We’re looking forward to the next Milestone, which we have only a few items in so that we can complete as soon as possible.  The main changes will be automatic lineraization (on user choice) of PDFs so that “Fast Web View” can be used, and the ability to avoid reprocessing FLV files which are uploaded.

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.

This release adds some polish to the user interface, fixing the email auto-completion feature, adding ‘loading’ icons to some ajax components, and adding filtering of users by groups to the management interface.  We also implemented “versioned assets” – in this case a relatively “dumb” way, by simply adding -MILESTONE_NUMBER to the the javascript directory.  This should fix issues we’ve had in the past with user’s having outdated assets stuck in their cache ruining their experience after an upgrade.

• 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.

Screencasts (aka screen capture movies)

Screen capture movie software (the “screencast” recorder) has been around for at least a decade. In essence, screencast recorders are virtual computer-screen camcorders. You install them and let them run in the background. When you want to record your onscreen activity, you press ‘record’ (usually a hotkey) and continue working. When you’re finished, you press ‘stop’ (another hotkey) and a full-motion movie of your activity is stored to disk. If you wish, you can record sound as well, most likely in the form of a running commentary spoken into the PC’s microphone. While there are many screencast programs on the market, iPOV has had good experience with the stability and value offered by BBFlashback and the features and performance of Camtasia.

Public screencast examples are everywhere. YouTube is full of them. So, wouldn’t you expect to see widespread use in large companies and organizations for internal IT training? That just seems to be starting. I suspect that there are at least 4 contributing reasons why it doesn’t seem to be as common as we would expect:

• Lack of Awareness – Screencast software is a surprising well-kept secret. We can’t count the number of times that we have spoken to programmers, program managers, and CIOs that don’t know even they exist. If we point them to examples on YouTube, they say: “I wondered how that was done”.
• Camera Shyness – It takes a certain amount of guts to record a movie that has your voice on it. What if you misspeak? What if you have a squeaky voice? What if you have a thick accent? All sorts of things can go wrong that will make you more nervous. Then you will make more mistakes and get even more nervous. Then you will give up.
• Lack of searchability – It takes time to demonstrate a complex software operation. Ten, twenty or thirty minutes is not uncommon. How many potential users have the patience to watch that much video to get an answer to a question? The problem is not getting to the right spot (most screencasts have tracker bars), the problem is knowing there is a right spot to get to. If only you could search the screencasts the way you search Google.
• No place to store them – Screencast movie files have gotten a lot smaller – but many are still too big to attach to corporate emails. That means that you need to put them on a web server or CD. If you accumulate a large collection, you will be talking gigabytes. Then how do you move them or find them. That brings us back to the searchability concern.

Until someone finds a way to overcome these issues, they will unfairly delay the adoption of this powerful and exciting technology.

Some Links with ideas:

• BB Flashback (free recorder and/or commercial editor)
• Techsmith Camtasia Studio (commercial recorder and editor)
• Jing (free recorder, but limited to 5 min run time)
• Screencast Software Comparison

Dual Monitor

With dual monitor support, you can hook up a second monitor and expand your laptop or desktop to double its size. This will give you enough screen real estate to support two applications that are fully open and functional. The application to the problem statement at the start of this diary should be obvious. With two monitors, you can open your application on one screen and the help window on the other. You can copy and paste from one to the other in one quick motion. You can read instructions in the help file as you follow them in the application.

Every notebook computer built in the past 5 years has built-in support for an external monitor. For desktop computers, you may have to add an inexpensive video card and a second monitor. The total one-time cost is typically less than $150 per seat. The return on that investment for a learner will be huge. Nonetheless, this capability is just starting to get the attention it deserves. You will find dual monitor setups in many software development shops and especially on trading floors, but not in most ordinary offices. Since there is no obvious drawback, it seems to be mainly an issue of awareness – and occasionally bureaucracy. One large company told me that all their IT support was outsourced to a 3rd party computer services firm. The service firm charged $100 per month for each monitor that it deployed!

Nevermind.

If, however, the PTB (powers that be) allow you to experiment with ways to achieve much higher productivity at a minimal cost, here are some additional tools and articles with more ideas for multiple monitors:

• Five Free Tools
• MultiMonitor FAQ
• Multi-Screens (banks of monitors)

• The edits are destructive – Most editing operations actually change video source. As the producer makes one edit after another, they create a complex trail of changes that is hard to reverse. If, for example, they complete the editing of a video clip and someone spots a flaw, the producer may have to go back to the beginning and repeat all of their work.
• Edits are made early in the development cycle – Since the edits are destructive, there is strong pressure to make them up front, get the video right, then proceed from there. Unfortunately, this means that if later work requires a change in the video, the work has to be repeated almost from scratch.

iPOV’s approach is totally different. iPOV can, of course, apply any of the familiar destructive editing technologies. If you want special effects on your video, we can add them. However, iPOV has developed a unique set of standard transformations that are inherently non-destructive. Applied in combination, our transformations can totally alter the appearance and content of the source video. As a bonus, our work is easily reversible up to the end of the development process and beyond. This makes maintenance easier and less costly. iPOV’s standard transformations fall into two main categories: visual transformations and content transformations that can be combined to create an amazing range of finished effects. The content transformations will be the subject of another blog entry. This one focuses on the challenge of visual transformation.

Visual Transformations

iPOV’s visual transformations are designed to alter the visual structure and appearance of a video source. They do some of the operations that are normally associated with high-quality commercial software. However, iPOV’s approach is totally different. iPOV has developed a powerful CoSolvent Flash Player (CFP) that does two transformations. Together, these can virtually slice, merge, reorder, overlay, insert, hide, zoom, slow, accelerate or freeze action – without altering the original video clips. The CFP runs in the Adobe Flash Player that is in the end-user’s web browser. In other words, the CFP applies the transformations as the movie is being downloaded to the web page. That’s as late in the development cycle as we could manage.

Transformation	iPOV Technology	iPOV Service	Goals
Construction	The CFP is a Flash application that assembles, orders, and plays a set of Flash movie clips in any sequence or timing on a virtual timeline. All of the action is driven from external XML specification files.	iPOV staff craft the XML spec files to client preferences for: Choice of sub-movies Order of components Component timings Inserted animations	The goal is to take all of the good bits and pieces from a set of raw movies and Flash raw materials and dynamically assemble them into a pleasing, seamless movie.
Enhancement	The CFP listens for commands from javascript or XML spec files. The commands can tell it to add subtitles, turn on a layer to mask a flaw, add symbols, or hide and reveal Flash animations and controls.	iPOV staff craft the source Flash files and XML spec files to: Add overlays Mask problems Add dynamic controls Highlight features	Apply the power of Flash layers to non-destructively change the appearance of the underlying constructed movie.

To be fair, a video producer, instructional designer or documentation author has lots of choices. There are excellent software and hardware products that do far more than iPOV’s transformations. However, commercial tools seldom consider overall project efficiency. To be efficient, you need to manage the visual changes from end to end:

• iPOV has defined formal procedures and guidelines for applying these visual transformations. With its procedures, iPOV can enforce consistency across long video clips or across all of the clips in a large collection.
• The spec files for the CFP can be revised throughout the content development life cycle and iPOV’s formal procedures enforce consistency across updates and revisions long after the initial authoring project is finished.

iPOV is very excited about the long-term potential for non-destructive transformations. Our CFP is just beginning its journey. There are many potential applications that we haven’t had time to explore and we are very eager to speak with potential clients that might be want to explore them with us. For example, we know that we could program a server to rewrite the XML spec files dynamically to reflect viewer profiles. That means that two website visitors might see totally different ‘mashups’ that are tailored precisely to their personal needs. The resulting mashups will each appear to play as a seamless movie. How many potential applications are there for that capability? If you have one, please contact us so we can discuss it.

You customized an ERP module with 15 new fields, 4 new screens, 5 significantly changed screens, a significantly different workflow, and an updated graphics ‘theme’. It takes you about 30 min just to walk a co-worker through all of the new features and methods. Now, you’re tasked to deliver end-user documentation and training materials ASAP. Your options are:

1. Open Snagit, grab lots of screen shots and start writing a Word manual – you should have it ready in a week or so.
2. Give it to the tech writers – they’ll pester you with questions, but they might have it done in a couple of weeks
3. Write a quickie memo and email it to end-users and let them figure it out for themselves – eventually.
4. Spend 1 or 2 hours on the problem and deploy it in multiple, professional formats a week from now.

The Typical Knowledge Asset Life Cycle

There’s an old management maxim: You must manage around your scarcest resource. For many (probably most) technology-intensive companies, the on-task time of their critical experts is a perennial “scarcest resource”. Despite that, companies routinely assign high-value talents to routine, mundane work – because they are the only people that can do the task. Nowhere is this waste more evident than in the production of “knowledge assets” like presentations, courseware, technical manuals, and operator guides. High-priced engineers work long hours with high-priced technical writers in one of the most inefficient processes in all of business. Worse, everyone hates doing it. If there is an engineer that loves writing manuals, no one at iPOV has ever met him or her. Yet they must do it because end-users need what they know. Under the best scenario, the task described above might go as well as is shown in this calendar:

If the participants are typical, however, the task will take much longer. The developer will be pulled onto other problems and won’t be able to write in a continuous effort. It may be a couple of weeks before the developer can finish the first draft. Then it will take time to schedule the reviews. Then more time to schedule an independent tester to verify that the procedures will work as written. Then the material has to be formatted and integrated into a document that meets the standards and is suitable for deployment. A task that might optimally be done in a week or two can easily stretch out for months. Finally, you could dump it all on a tech writer or outsource service. Let someone else figure things out from the finished application. Someone will still need to manage, review and validate their work. Hopefully they won’t pester the developer with too many questions.

What if there were a solution to this problem that was inherently fast, efficient and accurate? What if that solution made almost no demands on the developer’s time? What if the outputs were easily packaged in a wide range of deliverable forms: eLearning, manuals, class presentation materials, reference guides? What if the solution was less expensive than any method currently in use – even competitive with outsourcing to low-wage countries? What if the process was simple and incredibly easy to follow? What if that process was intelligent, culturally savvy and adaptable and would make the developer look really smart and competent? What if the developer could do everything he or she needed to do in a few hours after lunch, on a plane, in their hotel room on the road, or at home?

The Lean Knowledge Asset Life Cycle

iPOV has found a way to achieve the impossible. It just takes a total rethinking of the methodology – and a critical insight: The easiest way to write a software manual is to ask the developer to demonstrate the software and record the demonstration on video. With a thorough video demonstration, the developer can be excused from most of the subsequent documentation production process. The demonstration needn’t be smooth or professional. It can have gaffes and minor mistakes (if they are immediately corrected). The sound can be poor. A co-worker can knock on the door and interrupt the session. All of that is OK. There are only two things that are absolutely essential:

• A clear recording of the entire computer desktop and the developer’s commentary
• A thorough explanation of the topic details.

The first requirement is easy to meet with the latest generation of screencasting software (also see this blog article summary). Programs like camtasia and BBFlashback make this process simple and nearly foolproof. Install a standard Windows program and let it run in the background. The second requirement is met if the developer plugs a microphone into the PC and gives a running commentary to the video recording. The audio quality or the speech clarity is largely irrelevant. It’s purpose is just to record the developer’s thoughts. Flubs and gaffes and misstatements are not important. When these two requirements are met, the scenario in the problem statement can be satisfied with the following process:

In this process, the software developer’s only job is to share their knowledge on the video/audio recording. With no need to worry about minor mistakes, most people can learn to produce useful video in one or two takes. iPOV will take the recording and apply several transformations, most likely the construction, restatement, and possibly the extraction transformations. With these, iPOV can generate polished, professional eLearning and documentation materials that closely reflect the developer’s original intent. After the initial planning and recording sessions, the developer will only need to be involved in a review process about halfway through the process. At this point, the developer can edit the draft script to reflect what they would really like to have said.

Developer involvement is mostly independent of the content. The only exception is for recordings that rely on PowerPoint presentations or other forms of graphical documentation (e.g, UML diagrams). Preparation takes time – but that is true regardless of the recording method. At each stage, iPOV’s process generates interim deliverables that have an intrinsic value. In a crisis, the original developer recordings can be sent immediately. Whatever their faults, they are better than nothing. The review draft will have a script that has undergone significant grammar review and improvement. The final output is generally a SCORM-compliant learning object that is suitable for referencing in an online document or inclusion in courseware in an LMS. Other materials can be derived from this, including foreign language and print versions.

Bottom Line

In over 350 projects, iPOV has proven that this new method really works. iPOV has taken 5 hours of developer recordings and turned them into 5 hours of finished, validated eLearning materials in less than 3 weeks – start to finish. The developer’s time commitment was about 3 days! The rest of the time, the developers were busy getting the software system ready for deployment.

Why waste the time of the organization’s scarcest resource. Why put corporate initiatives in jeopardy by sidetracking your experts on mundane documentation? Why put projects in jeopardy by failing to distribute the documentation that end-users need? It simply is unnecessary.