Keep the Control in Your Hands

While I'm writing about S1000D, the same philosophy applies for transferring DITA, Docbook, and XSL/XSL-FO knowledge to your staff:

Our goal is to provide expertise to help customers grow to proficiency. We find that companies rarely need an expert on-staff. Expertise is expensive, especially when used for tasks that go beyond that initial expertise need. Experts are doubly expensive when paid to do tasks that do not truly require that proficiency. For example, why pay an expert on S1000D to write about airplanes just because the format is S1000D. A writer, who is an expert on airplanes, is much more competent to do the writing; the writer (significantly less expensive than the S1000D expert) just needs some training in using S1000D; they already have the subject matter expertise to do the actual writing task. In addition, the a writer, now trained in multiple doctypes, is a much more valuable, and flexible resource for you in the end.

As a result, our approach has been to provide the expertise and skills to companies who need intermittent expertise or who want a long-term relationship with an expert who can be available when necessary and who goes away when they're not. Intense training, implementation, and knowledge during the early stages of a project that helps our customers get customers.
We can participate as a de-facto member of your team and:

* Participate as a de-facto member of your team. We would participate as a technical expert in early project calls with your customer, lending you our credentials and experience so you have a better chance winning over your customers.
* Assist in implementing PTC's Arbortext products. We are an authorized PTC reseller and have more than 8 years implementing the PTC Arbortext product line for publishing.
* Mentor your staff. We assume that our customers do not want to be dependent on us. Part of our culture is to teach our customers to do everything necessary to do the current project and all similar project they undertake in the future. We truly act as mentors, teaching staff not only to do the work, but how to think about how to do the work, so they will be able to do the same kinds of projects independently in the future.
* Provide a jump-start for your staff. We provide a project-ready foundation, not just basic training. Our training and mentoring is always centered on your project. We help develop the work-product for your customer during the initial stages of the project while your staff continues to comes up to speed. This way, your customer sees immediate productivity and your staff has a usable basis for the ongoing product that they used to learn on.

In short, as a retainer-based consultant, we provide all the benefits of having an expert on staff without incurring the cost of having that full-time expert on permanent staff. We:

* Give you S1000D productivity immediately, giving your staff the time and space to come up to speed
* Train your staff in understanding, learning, and developing content that is S1000D-compliant
* Teach your staff to analyze and implement customer business rules in general
* Discover serious gaps in the any business rules you have received that will impact your ability to deliver content to them and drive resolutions to your customer
* Provide long-term on-call expertise, allowing you to amortize the cost over the length of the relationship and bill to actual need

Although expensive, the expert consultant is available over the entire project lifetime, and the cost can be amortized over the length of the project. Costs are billed only as used and have a guaranteed, built-in cap that corresponds to the proficiency of your staff--your ultimate goal. This method provides a guaranteed mentor and long-term resource for staff members to query and learn from, as they come across particular tricky or rarely-used content models over the lifetime of the project.

We typically propose a intensive training period at the beginning of a project. We us your data (or your customer's data), so your staff learns and produces at the same time.

Our retainer-style mentoring and training program stretches over the lifetime of your project and has a possibility of coming in well below the estimated costs. Final cost is completely based on your staff's progress and feelings of proficiency. By working with us, and amortizing your cost over time, you have the ability to improve your profit margin. The faster your staff progresses, the sooner your need for us ends, and the lower your final cost will be.

The progress your staff makes is completely with their own control. The more they work with the technology, the better foundation they start with, the more comfortable they'll be, and the sooner they'll stop feeling the need for an on-call expert to assist them.

The control remains in your hands, rather than ours.

And we like it that way.

The Complete Triangle

Attempting single sourcing with help from only one side is a recipe for disaster: Customers spend large amounts of money, resources and effort but don't get the system they expect. Customers should plan to research all three sides of the triangle and do a lot of planning from the start. Only then will they get a complete, extendable, and workable solution that benefits their entire company and sees return-on-investment from the very beginning.

Single-Source Solutions experts have implemented successful solutions by paying attention to all three sides of the triangle. Our implementers have presented at conferences and written papers about their previous experiences.

The Product Side: Vendors and Application-Specific Specialists

Product companies focus on developing full product suites to cover every possible customer. Their literature focuses on amazing application-specific features and why their products are the best choice for any environment. These companies work hard to sell products and consulting services to implement their full-scale systems.

Several vendors sponsor think tanks and white papers that help implementers understand the components to any single-sourcing system. Many provide resources for information on single sourcing and XML. Often these resources surpass the boundaries of their product line.

Some of the major players in the single-sourcing product space are:

* Arbortext
* Documentum
* XyVision
* More Vendors

The only problem with this side of the triangle is the problem that faces nearly every vendor. Competition is fierce. Products are expensive and generally so generic that it takes a considerable amount of customization before you have any sort of working environment. These companies do their best to make sure their products fit your requirements—rather than making sure that your requirements fit their product suites. It's a rare vendor indeed that recommends a competitive product instead of one of their own.

In the end, with any of these companies, customers will get an implementation that works. They all have professional services that provide expert implementation assistance. So, at that, they are very good. But this group too is missing the rest of the triangle. Often solutions are awkward and don't scale well to meet changing requirements as companies grow: they're focused on sales rather than the general theory and technology that are essential for a well-designed customer-specific solution. They miss the application-sepcific opportunities where documentation meets source development because they're desiging a system for the here-and-now. So again, we find that they are not alone.

The Technology Side: Programming Nuts and Bolts

The technology companies focus on XML as a programming language. The methods for code reuse, found in Object-Oriented programming literature, are similar to the methods used to achieve modular writing. Code reuse is the assertion that if you build generic objects they can be used and reused. It is the idea that you can isolate functionality into a module (function) and then use that module rather than rewriting the code. The ideas are the same. Unfortunately, the programming literature faces the same implementation gap, from the other side.

The XML programming books, which don’t describe its implementation as a language, describe the multitude of ways you can use XML. They tell you how to write the XML and how to process it: They do not tell you how to make XML work in a single sourcing environment. In addition, these books are not aimed at either of the groups that the single sourcing documentation targets. XML authors assume their readers have a programming background and already understand programming concepts.

* Books
* Online Resources

The only problem with this side of the triangle is that nearly all of the literature is technical in nature. Most books on XML contain information about programming XML applications—from programming XML compilers to web-services. At this, they are very good. But this group too is missing the rest of the triangle. The components that bridge the nuts and bolts of technology and real-world practice. And, once again, we find that they are not alone.

The Theory Side: The Information Management Consulting Companies

There are a lot management consultanting companies who specialize in best practices: the theory of singlesourcing. Their literature is full of information about strategies, document design techniques, and how to choose a tool or evaluate a product. These companies work to create standards and generalized rules for making single-sourcing work in traditional publishing environments.

These companies have excellent information on their websites about how to get cost savings through single-sourcing, how to write modularly, or how to structure your documentation. When you're first learning about single sourcing, you can't find better resources:

* S1000D Technical Publications Specification Maintenance Group (TPSMG) TPSMG is responsible for the development and maintenance of the ASD/A1A S1000D international specifications. S1000D describes a standard for the creation and publication for technical publications utilizing a common source database

* The Center for Information-Development Management Founded by Joann Hackos, the CIDM provides "a focused, expert, and progressive forum to support documentation, training, and customer service managers in creating high performance teams that produce effective and appropriate deliverables."

* The Rockley Group Members of the Rockley group work with clients to develop "information solutions through a unified content strategy, either for a particular project or across an enterprise. "

* Single Sourcing: Building Modular Documentation by Kurt Ament This is one of the only books that attempts to bridge the gap between the single-sourcing theorists and the technology developers.

Hackos, Rockley, Ament are, to a significant extent, the existing authorities in theoretical single-sourcing and information design. Their websites have everything the beginning single-sourcer could need. Their books (and conferences) are extremely useful. They are full of detailed information to teach managers, writers, and document designers how to think about single sourcing.

The only problem with this side of the triangle is that nearly all of the literature is theoretical in nature. Most books on single sourcing contain advice about planning, managing, and creating modular projects and documentation. At this, they are very good. What they’re all missing is the rest of the triangle. The components that bridge theory and practice. And they’re not alone.

The Single-Sourcing Triangle

Single sourcing is a simple idea that requires a very complex implementation. Single sourcing is a methodology, not a technology. XML is a technology, not a methodology. Bringing the two together is not obvious or well-defined. No one system that works for every customer. No one book describes how to put it all together. On this page, you will find places that will help you figure out where to start.

One of our goals is to help customers make the choices that will allow them to implement a system that scales. Necessarily, for any concrete project we must choose a set of tools and we must decide how to implement particular components.

At Single-Sourcing Solutions, we remain vendor-neutral and platform-agnostic. Most importantly, we avoid unnecessary customization, so that our customers can take advantage of new products and new technology down the road.

The Single-sourcing triangle includes the Information Management folks (theory), the Programming folks (technology), and the Vendors (products).

What we do

Single-Sourcing Solutions experts bring XML technology and single-sourcing theory together to make "write once, publish everywhere" a reality.

The goal of any single-sourcing project always the same: To increase the efficiency of the entire staff as the demand for documentation increases while staffing and resources do not.

Successful single-sourcing solutions address several key needs:

* The authoring environment must be user-friendly and easy to learn.
* The look and feel of the published documents must be comparable to the existing published documentation.
* The environment must scale easily, so that it can be altered and enhanced without major infrastructure changes going forward.
* The tools and processes must fit customer project needs.

For us, single sourcing is more than just theory. It's a practical, reachable goal for any company.

Single-sourcing environments promote efficiency and productivity by reducing maintenance and overhead. Our team looks for the tools that support scaling and productivity. We tune existing skills, workflow, and processes to new tools that help single-sourcing efforts achieve success in their environments.

What we do:

* Full-Gamut Single Sourcing: Code, Definition, Help, Documentation
* Automated publishing to multiple media: print, PDF, Web, Palm, eBook, CD-ROM, wireless
* Develop tools to facilitate document creation and editing tasks
* Deliver classroom instruction with sample documents and exercises tailored to your business
* Assist legacy documentation conversion
* Application-specific XML tools development

To customize or not to customize

The Arbortext product line is not a turn-key solution. Through no fault of the software itself, there remains a certain amount of work that must be done before the whole solution will deliver production-ready documents. The fault lies in the intersection with available XML technology and customer-specific needs and requirements. We encourage our customers to pursue standards-based, customization-free (or -light) implementations. Standards-based solutions ensure customer's get the best for their needs.

Application-specific XML tools development

"Any Application, Any Industry, Any Project, Any Platform"

Opportunities for application-specific XML integration exist everywhere in the product-production life-cycle. Technical Publications organizations have been pursuing single-source solutions primarily to solve issues of quality and production of multiple-output formats. As these organizations mature, many look at ways to automate document creation as well. The tools and applications that we provide are true cross-industry applications.

And, if single-sourcing for reuse and automatic documentation production is the first step, then the exporting of content to other business organizations is only the second. The third step is to look at the entire product development process to identify opportunities for automatic content creation because mechanically-produced schema languages can be converted automatically into documentation and documentation templates.

This means that opportunities for practical XML development and deployment include:

* Full-Gamut Single Sourcing: Code, Definition, Help, Documentation
* Revision Management: Where Source Development Meets Documentation
* Application-specific XML tools development

For example, many applications have XML interfaces. For products that take advantage of XML as part of their implementation, creating tools that can automatically generate documentation is an obvious target for integration into a single-sourcing solution. For products that don't, tools can be created that transform native programming languages into XML, as needed for documentation purposes.

More on application-specific XML tools development

Auto-Generate Content From Documentation

Documentation is the foundation for a product collateral and for support reference material. Information about specific technical requirements and product specifications is duplicated in technical manuals, marketing collateral and support knowlege bases. Keeping information current and in synch in all of these places is an enormous task when all these systems are isolated, separate systems.

Customers get better, more accurate, and more consistent information when the information creation and publication is tightly woven together in a single-sourcing system.

* Improved Customer Relationships
* Improved Data Integrity
* Consistent, Accurate Information across the business

Application-specific XML tools development can improve accuracy and information integrity for customers. By developing tools to integrated independent business systems into a larger single-sourcing environment, you see an immediate improvement in data integrity. And customers see an immediate improvement in their relationship with your company.

These are just some of the many ways that other organizations with your company can benefit from content generated from Technical Documentation are:

* Online help required in the Product Source Code
* Technical Support Knowlege Base Articles
* Marketing Whitepapers and Data Sheets
* Customer and Partner Portal Content

Benefits of application-specific XML tools development

Auto-Generate Content For Documentation

Documentation for technical manuals can be generated directly from the product source code or other engineering systems. Technical requirements and product specifications can be found in source control repositories in varying formats. Product-specific information may exist in operations databases, price lists or manufacturing database systems.

* Unlock Isolated Business Systems
* Auto-Generate Content
* Simultaneously Generate Content

Writers in Marketing, Technical Publications and Technical Support Groups all independently generate all of the the same content from all of the same business systems across the Organization. Without a single-sourcing environment, all these groups generate the this content repeatedly as the details change and the information, locked in the various business systems, gets updated over time.

Application-specific XML tools can unlock the isolated business systems and compile information to auto-generate content simultaneously for:

* Technical Reference Manuals
* Time-Sensitive Release Notes
* API-Specific Implementation Information

Revision management

Where Source Development Meets Documentation.

In traditional publishing environments, source control is minimal if it exists at all, and often follows the lock-modify-unlock model that prevents simultaneous, collaborative, content authoring.

Single-sourcing environments require source control management to manage the reusable content stored in topology-specific libraries (including images).

* Independent Change Tracking
* Historical Change-Tracking Reporting
* Simultaneous, Collaborative Document Authoring
* Partial-Regeneration for Fully Updated Output
* Multiple Documents Created from One Source
* Reduced Translation Costs

Source Control and Content Management. The best content management system is the one that matches your business requirements and your information model. Choosing a content management system can be easy or hard, expensive or cheap. If your analysis is sound, and your information model well developed, you can always avoid both expensive and hard.

Multiple-Document Profiling. XML technology and metadata provide a way to create multiple virtual documents from one original source document.

Reduced Translation and Localization Costs. XML is ideal for reducing translation and localization costs. Because information authored in XML is in a structured, non-proprietary format, translators can get document fragments that show only the changes between one revision of a document and another. Translators only translate the changed parts.

Integration with Product Development. In some cases, the document creation and publishing process can be integrated directly into the source development system. In other cases, the source development system may be an output target of the publishing process. With proper planning, the single-sourcing system can be integrated directly into the source development system.

Full-Gamut Single-Source Solutions

Code, Definition, Help, Documentation and Training

Single sourcing is a simple idea that requires a very complex implementation. By leveraging XML technologies and single-sourcing methodologies, our experts develop the systems that support every member of the technical publications team.

Mission-Critical, Custom XML Applications in single-sourcing environments can help all the members of the technical publications team:

* Authors can write content once and use it everywhere
* Editors can run reports on content before sitting down with a hard copy
* Production editors can automate production tasks
* Everyone can Focus on Content, not Formatting

Single-sourcing makes reuse possible. Content can be used multiple times within a single book or multiple times across multiple books. Writers and editors can focus on writing content, rather than formatting content. Reuse, automation, and the separation of content from format, improves the efficiency of every member of the technical publications team.

One Source, Many Outputs. Single-Sourcing Solutions consultants help customers output for all required mainstream output formats including: Web, CD-ROM, Palm, ebook, and Online Help. Through application-specific XML application development, we can produce other output formats tailored to your specific business requirements.

Vendor-Neutral, Platform-Agnostic. Our vendor-neutral, platform-agnostic approach guarantees that we design a system that is specifically tailored to your business needs.Single-Sourcing Solutions helps customers make the right choices every step of the way.We help you define requirements that let us choose the best tools and the best way to implement particular components.

From Analysis to Training. Our team begins with a complete analysis of your existing documenation set and business processes. We develop all initial applications and content management repositories, and then train your people on every component and every tool.

On Content Reuse

A truly excellent post on content reuse guidelines and threshholds was posted today to the stc-single-sourcing mailing list.

Julie Kumasaka asked: "Does anyone use a guideline or has anyone come across a guideline recommending what percentage (or some other measure) of text from two sources should be the same to be worth single-sourcing them?"

Mark Baker (mbaker@analecta.com> posted an excellent reply:

I see this topic has generated a lot of discussion, which, unfortunately, I don't have time to study properly at the moment, so I will offer the following thought and hope it is not totally redundant with what has already been said.

The point is not to reduce redundancy in content. The point is to reduce redundancy in effort. Reducing redundancy in content is just a means to that end, and it should only be done when it can be shown to achieve that end.

In the case of conditional text, it makes a huge difference whether the conditional content is volatile or stable. Setting up and testing conditional text is more work than simply writing the content twice. The win comes if using conditional text for some content lets you reduce the effort of maintaining other content.

If the stable parts of your content are conditionalized, you only have to go through the pain of setting up the conditions once. You set it and forget it, and then just update the unconditional content whenever it changes. In this case, using conditional text saves you a lot of effort, no matter the proportion of conditional to unconditional text.

On the other hand, if the volatile parts of the content are the conditional ones, you will constantly be maintaining the conditions, still writing two different pieces of content, and having additional work to test your conditions. In this case using conditional text will not save you effort and may create additional effort. Again, this is true no matter what percentage of the content is conditional.

In short, if you conditionalize stable elements of your content, you win. If you conditionalize volatile elements of you content, you break even at best, and probably lose. Looking at the balance of volatile vs. stable content is therefore a better indicator than looking at the percentage of conditional content.

Mark

How to Evaluate a Vendor

I never trusted the vendor-provided survey/ROI reports. They're useful to turn in after you've chosen them, but I always tried to get funding enough to take one of the vendor's low-level training classes. That's a lot cheaper than buying a product and then finding out it didn't hold up (why does any company think it's a good idea to just buy and find out?). The training class method is good, because, when they're training you on a product, you usually have someone who knows the product inside and out. This gives you a direct channel to ask better questions and get the real answers - instead of the sales-guy spiel. Might be an option?

Gathering requirements is a difficult task. There are always some general requirements that fit with nearly every single-sourcing project.

These kinds of requirements break up into the following categories:

General System Requirements

Requirements for all applications and vendors

Additional XML Authoring Tool Requirements

Additional Workflow Tool Requirements

Performance Requirements

Data Object Requirements

Network Requirements

Benchmarks for Requirements Verification

These are the underlying requirements that define any good system: the ability to control document source, the ability to create and produce documentation products for customers. The goal of a good requirements document is to capture and define requirements for a new system above and beyond these basic requirements. A good requirements document includes these basic, best practices requirements, in addition to the problem-specific requirements that can only be defined in terms of your business processes and needs.

These are the kinds of requirements will help to ensure a system that encourcages user participation. It helps you to design a system that can provide real benefits to the user and to the company. A well-designed system will provide many opportunities for small efficiencies in addition to any benefits due strictly to upgrading to new technology.

It is my intention here, then, to lay out some best practice requirements, to get requirements documents writers started. This is a jumping off point. Not an end point. The real end point includes all those intangibles that only you know about as the in-house expert, the requirements document writer.

General System Requirements

Can keep data local to task

Minimizes overhead

Fits into existing business practices

Optimizes, improves, or otherwise streamlines existing business practices

Does things right

Does not compromise customer-driven or business-driven requirments

Avoids unnecessary structure for the sake of structure

Can customize metadata/structure to reflect real business requirements

Guarantees functional quality with required output systems

Guarantees informational integrity

Improves quality

Improves accuracy

Improves flexibility

Guarantees consistent presentation

Supports authoring

Supports editing

Supports document management/configuration management

Supports workflow/tracking

Supports production

Requirements for all applications and vendors

Is currently supported

Uses current technology

Has plan for incorporating new technology

Has clear path for upgrades

Has clear plan for product deliveries

Is customizable

Is extensible

Has clear, defined plan for upgrading customization code

Supports automation through customization or extension

Application itself can be automated

Designed to scale to meet new customers and future company requirements

Additional XML Authoring Tool Requirements

Compatible with graphics output (e.g., SVG, CGM, EPS, TIFF, GIF, JPG, PNG, BMP) output

Compatible with graphics input (may be same as or a subset of those formats listed above)

Vendor has lifecycle policy

Produces documents that are of comparable quality

Supports content reuse

Supports custom-defined chunking

Supports smaller than single-document chunking

Additional Workflow Tool Requirements

Has control mechanisms

Has approval mechanisms

Has guaranteed audit trail

Records transactional historical data

Tracks user tasks and events

Records: state transistions, approvals, times/dates, routing activities, user

Can automate the creation of ancilliary documents

Can interact with other external systems

Can fire off external events

Can be advanced through external mechanisms (e.g., API)

Can store additional metadata about stored data objects

Uses Lock-Modfiy-Unlock or Copy-Modify-Merge (Specify which)

Can define roles

Can define access requirements

Can use role-based access to guarantee entitlement

Integrates with LDAP

Supports execution of custom, exernal, automation tools

Performance Requirements

Side-by-Side Performance Test

Check-in/Check-out Directory

Check-in/Check-out Single-File

Check-out of documents for edit

Check-out of documents for read-only

Level 1 Workflow testing (edit, route for review, annotated, dispatch)

Level 2 Workflow testing (Level 1 + re-edit, 2nd draft, route, dispatch, approval)

Level 3 Workflow testing (include full production run)

Testing with multiple clients/multiple users

Tangible improved level of functionality achieved

Tangible improved level of performance achieved

Tangible improved level of integration achieved

Data Object Requirements

Binary Document types (MS Office, FrameMaker, PageMaker, Interleaf, etc)

SGML Files

XML Files

Metadata extraction from SGML/XML file (CMS integration)

XML/SGML file internal link management

Binary graphics file type: EPS

Binary graphics file type: TIFF

Binary graphics file type: GIF

Binary graphics file type: JPG

Binary graphics file type: BMP

Binary graphics file type: WMF

Binary graphics file type: CGM

Network Requirements

Directory structuring

Permission structuring

Roles-based permission entitlement

Benchmark Test Requirements

Task: Authoring Application Launch

Task: CMS Launch

Task: Check-out directory

Task: Check-in directory

Task: Create new document

Task: Delete document

Task: Grant user permissions/access

Task: Change user permissions/access

Task: Look at object properties/metadata

Task: Look at object history/audit trail

Task: Retrieve old version of document

Task: Check-out single-file-document

Task: Check-in single-file-document

Task: Search for document

Task: Change user ownership

Task: Generate object report

Task: Check-out SGML/XML-document

Task: Check-in SGML/XML-document

Task: View Tasks/Jobs

Task: Acknowledge/Claim assigned task

Task: Review Task

Task: Add Reviewer

Task: Approve

Task: Dispatch

Task: Create revision/tag/branch

Task: Create release

Technorati Tag: single-sourcing

Avoiding Vendor Lock-in

The goal of object-oriented tool development is to avoid vendor lock-in. Lock-in is not determined by the cost of the application but by the method of its implementation. The level of integrated customization determines the level of vendor lock-in.
One-of-a-kind software (fully custom or “one-off” software) is both desirable and necessary when no other solution is available. Unique software is custom-built for one specific purpose; it cannot be used by multiple customers and cannot be rented.
Customizable software (tightly integrated software like Vulcan) was a natural development of productized custom software. Customizable software was an attempt by vendors to create generic applications that could be set up according to individual business requirements, specifications, and needs. In a very real sense, customized software is harder to upgrade, expand, or replace than completely unique software: customized applications have as much single-purpose code as they have COTS application software, but the single-purpose software is tied to both the particular COTS application as well as the particular COTS application version. This means that all of the customizations must be upgraded whenever the application upgrades, if it can be upgraded at all.
Open standards software development (API tool development) is a direct response to the customizable software development over the last 20 years. API tool development focuses on isolating the impact of an application-specific code. For example, rather than implementing customizations entirely inside a particular vendor’s customization language, API developers create the small custom tools required to implement specific business requirements. They isolate required functionality in a small custom code components and then build an API layer to communicate with a specific vendor’s application. This way, when the application required upgrade, developers only need to upgrade the API layer: the customization layer does not significantly retard the ability to upgrade or replace any particular vendor product at any time.
That is what vendor lock-in means.
NGES-MS is facing this situation with Vulcan today. Vulcan is tightly integrating the functionality of Epic with Visual Source Safe. As a result, NGES-MS is tied to Epic 4.3.1. Although Arbortext charges an annual maintenance fee, we cannot upgrade Epic to take advantage of new features, Because Vulcan is customized COTS software, upgrading Epic will not occur until Vulcan upgrades all of their 4.3.1-specific code.
In addition, NGES-MS is facing a deadline: it is highly probably that Interleaf will stop functioning with the next release of Windows (Windows Vista). Interleaf has been in use at NGES-MS since 1995. Interleaf might have still retain long-term prospects, if other factors were not at work to place the documents and data it supports at extreme risk. NGES-MS discovered that with the release of Windows XP, RDM became inoperable. Windows XP is scheduled to reach end of life in 2006. Extended support will end 5 years after mainstream support ends, in 2011. Documents still in Interleaf after 2011 will likely be unrecoverable.
Today, 78 percent of NGES-MS Launcher documentation is not supported in the Vulcan/CAE data model. Given the laundry list of features currently facing the Vulcan development team, it’s unlikely that Vulcan will be able to support the additional document types in time and we would simply be exchanging one highly-customized, proprietary system for another.
On the other hand, S1000D is written with interoperability in mind, but without limiting this to the lowest technical application. Although it may appear rigid or involved with tracking irrelevancies, the specification defines application behaviors; it requires vendors to provide data interoperability (a “way out”). If a product claims S1000D-conformance, developers supporting this format will never find themselves held captive. If a vendor is compliant, support staff will always have at significantly less expense options than if they were dealing with a proprietary or highly customized environment.
S1000D is not a tool. By its own definition,
S1000D is an international specification for the procurement and production of technical publications.. for [use in] the support of any type of equipment, including both military and civil products. (Chap 1.1, Page 1)
For the first time, interoperability is considered important from more than the technical (software engineering) perspective: a usability perspective is also involved. The uniform presentation of content increases both author and user efficiency. If every manual is created in accordance with the same specification, and content is always presented the same format, the learning curve for new personnel can be drastically reduced. In fact, a novice user becomes productive much more quickly without interference from the manual, in order to complete the job at hand. The majority of the S1000D specification addresses this very issue. By thoroughly defining how manuals should be constructed, the specification improves overall quality for every single person who uses the manual.
Besides defining the schema and enforcing interoperability, the real revolution S1000D offers is that it is completely modular. A data module is a data module is a data module, and output is done via assembly. S1000D will force users to change both the way they work and they way the “have always done things.” New policy decisions will be required. S1000D requires changes because, it demands following best practices. The end results, the benefits, really do outweigh the costs.
Can projects using S1000D be tailored, expanded, and customized? Yes.
Do you have to use their process? Yes.
Do you have to change your processes? Perhaps
The best part of the S1000D specification is that, once agreement occurs between user, customer, supplier, and other internal groups, the implementation can still be tailored business requirements.
The "known standard" benefits are self-evident.
As with other documentation formats, S1000D reduces support costs, facilitates modularity and reuse, and allows users to view electronic documentation via a common Web browser or other interactive electronic technical manual (IETM) viewer.
S1000D indicates that it is flexible system. In contrast, most of the commercial world is adopting IBM’s Darwin Information Type Architecture (DITA) format. Many early DITA users have struggled with its overly generic character.
This was a conscious choice by the DITA architects: DITA legislates only the framework (topics, tasks, references, et al), but requires users to flesh out the details through "specialization." Those who have used DITA out of the box have customized it and are now looking for something better.
S1000D is better. While it has many similarities with DITA, it goes even further. S1000D represents an emerging technology. This means that the tools are not fully developed and that vendors have not yet fully embraced it. However, because many organizations are adopting it, vendor support will grow. Working with this standard, we can leverage the same benefits that we would get by using any other.
S1000D is specific to air, land, and sea systems. S1000D captures more information (for documents supporting these products) than any documentation format to date. The specification is essentially complete. S1000D is ready to use today. It has more leverage for information authored and for tools that serve documents, on a smaller-than-document-level basis. In addition, S1000D has significant COTS vendor support and a wide community of practice to draw upon.
Because the DOD has specified that new documents be S1000D-compatible, and because migration is inevitable, going to the new system now is most cost effective. S1000D is XML, and XML transformation tools are immediately available. S1000D is the full-blown schema; all that remains are refinements of the data that the S1000D format contains.
We see several valuable side effects of this implementation. First, we believe that S1000D provides a neutral response to the DOD. This gives the entire SP community adequate opportunity to say: “S1000D is being investigated.” Second, the trial implementation provides a genuinely independent evaluation: NGES-MS has no interest in one system over another and can evaluate S1000D without impacting other deliverables.
Third, because we will be supporting Vulcan output as well as IETM and pdf, as a bonus, we will be able to provide the roadmap for Vulcan-S1000D transformations without delaying current deliverables, or diverting attention away from current development efforts. If S1000D/Vulcan interoperability ever becomes desirable, the SP community will know the requirements, how much work will be involved, and a starting point (our transformation code). This information becomes available without derailing current deliverables or distracting the Vulcan implementation team from their primary focus.


Technorati Tag: single-sourcing

Tight-vs-Loose Integration

Products that support open-standards development are essential for successful single-sourcing projects.

The experience of end users is better when they are not faced with complicated procedures to get their jobs done. Many implementors try to achieve this goal

From a customer's perspective, applications that provide prefer things not to be tightly integrated -- from the vendor. That kind of integration guarantees vendor lock-in. I like being able to develop custom tools that join systems together (automating the systems as much as the systems automate process).

The one thing we all know is that no vendor lasts forever, so I avoid vendor lock-in and tight vendor integration as much as possible.

Sadly, I'm seeing the bad-side of that right now. We had both RDM and Interleaf. IT has just started migrating all the documents out of RDM and into Livelink, but everyone who's ever used RDM + Interleaf is having a horrible time understanding what RDM did and what its purpose was. And it's all due to how tightly they were integrated by Interleaf to start with. They integrated so tightly, because they knew how both sides were implemented (and were doing both) that they took short-cuts and hid things from the users. Now, the users can't make the shift because they never saw the lines between the products.

I prefer applications that support development of application-specific XML tools. Tools that can unlock isolated business systems: for example, import or export data between systems or applications, auto-generate data, automate applications as well as processes.

I'm genuinely afraid that the tight-integration path is the path Arbortext is heading down. Their recent product development (DCAM) coupled with their recent acquisitions point directly to their plan to integrate tightly.

Note that two integrations in two months is very frightening, because it takes way longer to integrate than that. I went through three integrations at Juniper, and I can tell you from experience that it's 6 months to a year before products even start to really plan the integration path.

Personally, I liked that Content@ dropped the raw documents into a catch-all directory. With a situation like that, I can do a lot of pre-processing or post-processing: like generating documents to report errors to writers.

I don't mean XML/DTD errors. I mean errors like .. The style-guide errors that aren't otherwise checkable by the parser alone. For example: I can generate a report to the author that tells them that using two titles in a row without a paragraph between them, or with only an empty para between, is an error.

There's all kinds of space to do this kind of post-processing when products aren't tied together.



Technorati Tag: single-sourcing

Single-Sourcing is a Software Project (not a Documentation Project)

Understanding the staffing requirements for a production quality single-sourcing system depends on two things:

1. understanding the difference between IT and engineering
2. understanding why a group, which has not (at least in recent history) required specialized skills to operate, suddenly does

Think of IT as a mall and TechPubs as a Store in the mall.

Both the mall and the store have specialized staff who help run their business. Both groups have staff members who are responsible for the operation and success or failure of the their particular business. The store depends on the mall to provide a physical location in which the store can do business. The mall depends on the store to provide a source income in order for the mall. The mall depends on the stores it houses to provide attractions that bring consumers to the property. The stores depend on the mall to prived a safe and secure location for customers to do business. Both groups have responsibilities that center around the same customers; both groups work together to achieve the same goal.

But they don't use the same staff to operate both businesses. While the two groups would have several staff members with overlapping skills, these same staff members have completely different focuses. For example, both groups have sales associates. The sales associate for the mall would never be the same sales associate for the store. If the staff for both groups were the same, the mall would be responsible not only for the operation and success or failure of the mall itself, but the success or failure of the stores operating within it as well. This would mean that the mall's sales associates, who would normally be selling space in the mall, would not be doing that because they would be spending their time selling products at every store in the mall.

The focus for each group is fundamentally different. For the mall sales associates, every sale is a single sale: a one-off deal. For the store sales associates, every sale is a repeat sale: every sale is tied to the dynamically changing nature of the rest of the store.

The store can afford to try different approaches, to move products around. If one display works, then everything's great; if it doesn't, then the sales associates change the display and try something else. One failure isn't fundamental to successful operation. More importantly, because of the frequently changing nature of the store, one bad display, particularly one that isn't there very long, isn't visible to customers.

It's different for the mall sales associates. Stores contract locations for long periods of time. Malls cannot afford to have individual store spots empty for long periods of time. One bad contract can mean success or failure: and that success or failure is glaringly obvious to everyone who comes into contact with that mall.

The same things are true of engineering and IT. Engineering groups can try different things out; they can change things on a daily basis in order to improve they way they operate.

IT doesn't have that luxury. IT focuses on projects that support the entire business structure. IT's failures are failures that everyone sees. A failure for IT is a big problem: it's lost money. As a result, IT cannot afford to have people tied up supporting engineering groups on a daily basis. Successful IT organizations bank skills in order to deploy teams to implement and manage the large parts of one-off projects and then move them off to the next one.

TechPubs is one store in the Mall. TechPubs has products and customers and requires a certain amount of infrastructure support from IT, in order to operate effectively. However, in recent history, TechPubs has not required specialized skills, that have overlapped with skills traditionally found in engineering or IT organization. With a single-sourcing system, that's no longer true.

Implementing a single-sourcing system is not a trivial replacement of applications. Since the mid-80s, technical publications departments have been able to trade authoring tools with very little assistance: Let's use Interleaf! Now, let's use FrameMaker! Look, PageMaker! Microsoft Word!
These applications could easily substitute for one another on the author's, editor's, and text processor's desktop computers.

With an XML authoring and production system, this is no longer true.

For example, authoring consistent and publishable documents in Microsoft word requires adherence to a Microsoft Word Template (.DOT) that governs the styles, spacing, and pagination of a document authored in Word. IT would maintain the Word application on each author’s desktop, but it would not normally develop the .DOT template document. Word user specialists would create, maintain, and deploy the .DOT template to the authors using the application. So, just as IT would maintain the authoring application and the publishing application but not maintain or develop the required templates for publishing from a desktop publishing application, they would not do that development for an XML publishing system either.

Look at a typical PeopleSoft implementation. IT would maintain the application, machines, and application specialists. They would typically develop and maintain the workflows that are required for efficient processing. The HR department would also have a PeopleSoft specialist, who would administrate the application, train new users, and provide or restrict access to certain records in the database. In an XML authoring environment, IT would maintain the database and repository, from the application perspective, but someone from TechPubs would have administrate, train, and provide or restrict access to documents in the repository.

In a very general sense, every IT project is a "one-off," a singular project that supports part of the enterprise. IT costs are overhead costs. As a result, if an IT project doesn't work, it's a big problem: the company has lost money on it.

In contrast, functional tools teams can support proactive projects: try something, if it works, good, if it doesn't work, it's not a problem. Engineering organizations are expected to try apply new approaches and new technology to existing problems. Likewise, functional tools teams who support engineering products can also do proactive software development.

For a single-sourcing project to be successful, the way you define the line between the IT team and the functional team (the "tools" team) becomes important. In many ways, this depends on the charer IT has in your enterprise. At Juniper, IT had a very specific job: whenever company purchased a new application, IT would dive in, learn everything there was to know about it, and support it. But they rarely went beyond that point. If an organization needed daily support, they added a functional tools team that took things from there.

IT builds the roads, the functional group buys the cars; the functional tools team customizes and maintains the cars, all while following IT's rules for driving.



Technorati Tag: single-sourcing