PDS / MadCap Software Events in Nieuwegein and Antwerp

I will be travelling with our partner PDS to do two public sessions covering a full introduction to all of the MadCap Software products. These events will be in Nieuwegein, Netherlands on November 11 and in Antwerp, Belgium on November 12. The schedule for these events:

13:30 – 13.45 Registration and coffee
13.45 – 14.00 Welcome by PDS
14.00 – 15.00 Theory Madcap Flare+MadCap tools
15.00 – 15.15 Break
15.15 – 16.15 Demo: Flare 4.x, Lingo & MadCap tools
16.15 – 16.45 Q&A
All your questions will be handeld by RoboHelp & Flare experts.
16:45 –         end of seminar

 These sessions will also include a live demo of the new DITA functionality planned for release early next year. More details can be found on the PDS MadCap Roadshow page. The slides for the event can be downloaded here:

MadCap Software Overview Slides

From Boston on to Germany for the Tekom show

Every year the Tekom / TC World event is held in Wiesbaden, Germany. This has to be the largest show in the world dedicated to technical authoring and publishing. This year the show was from November 5 through November 7 and around 3,000 attendees and three halls full of exhibitors were in attendance.

For several years now we have been helping to staff the booths of our partners and resellers, but with the way we are growing we just have too many partners to support! So, this year MadCap Software had our own booth at Tekom.

MadCap Software booth at Tekom 2008

It was a major challenge trying to coordinate everything from the US, but in the end it turned out great! We met a lot of great people from around the world, did countless software demos, and gave away some free software to the lucky prize winners. We also spent some time supporting our amazing resellers in Germany Cognitas and Help Design.

Now that the Tekom / TC World show is behind us I am heading off to the Netherlands and Belgium for some public events with our parnter PDS.

MadCap at DocTrain East

Boy, the blog has gotten away from me for a bit. It has been a busy trade show season. In fact, I am typing this post from the DocTrain East show in Burlington, MA. Earlier today I had the honor of presenting two in depth Flare sessions to a great group of folks and several asked about getting copies of my slides. Rather than clogging up email inboxes I though it would be easiest to simply post them here.

 Wednesday pre-conference sessions:

 MadCap Flare – An Introduction to Topic Based Authoring

MadCap Flare – Content Control and Publishing Techniques

Thursday night STC presentation:

Software Simulations and Interactive Tutorials

Saturday post-conference session:

MadCap Flare – Controlling Document Look and Feel with CSS

MadCap Software announces MadCap Flare, Version 4!

Most new software releases have two or three major new features with a handful of minor features, but we lost all control with this version of Flare as there are no fewer than 60 new capabilities! Far too much to list here, for a comprehensive list see:

http://www.madcapsoftware.com/support/webhelp/flare/Default_csh.htm#/Introduction_Topics/Whats_New_in_This_Version.htm

Briefly, some of the Flare V4 high points:

Global Project Assets – Now share all of your images, CSS files, or any other element across many Flare projects.

Collaboration – An industry first! Send any of your topics to any reviewer and they can review and annotate without needing Flare! Also, create templates that staff can use to contribute to your Flare projects without having to have Flare.

Print engine – from good to amazing! Total page layout control including multi-columns per page, automatic text routing between columns, ability to switch between landscape and portrait anywhere in the document, a new Flare authoring mode dedicated to a print-centric experience, direct output to PDF or XPS, and more.

To see Flare in action sign up for a free
web-based demo, or to download the free trial, go to
http://www.madcapsoftware.com/products/flare/ .

MadCap Flare Best Practices – Project Size

I’m going to try something different here in the old blog. I’m going to do a short series on some of the questions that seem to come up over and over to help out those people who are new to our industry. The first question I will tackle is:

What is the optimum size for my Flare project?

This seems like a simple question, but it is actually very difficult to answer because, as with so many other things in life, “it depends”. I have seen small Flare projects that were perfect for company A and I have seen HUGE Flare projects that were perfect for company B. The important thing is that your projects meet your specific needs. To achieve that there are some guidelines that can be followed.

Guideline 1: Smaller is better

All things being equal it is easier to author and work in smaller projects. When you need to find that one specific graphic you need it is much easier to find it from a library of 50 images than from a library of 5,000 images. As projects scale you simply have more data, images, files, and other assets to sift through to find the specific item you are looking for. This isn’t necessarily bad and we do provide tools to make this as easy as possible, but in broad terms smaller projects tend to be more efficient for authors to work in. But…

Guideline 2: Too small is bad

What! You just said that small is good! Yes, that is true, small is good but too small is bad. Fortunately there is a very easy test to let you know when your project is too small. If you ever, Ever, EVER find yourself having to make the very same edit in multiple projects that is an immediate sign that those two projects would likely benefit from being merged into a single project. The very concepts of content management, single-sourcing, and multi-channel publishing are based on the ability to edit content only once and then re-use as necessary. If you have to make the very same edits in multiple projects then the projects are definitely too small and are hurting your ability to single-source publish rather than enhancing it.

Following these two guidelines can help you to determine what the optimum size of your projects should be. In the real world I have seen 300 topic projects and 20,000 topic projects and both were “just right” for their particular environments. The bottom line is to not get  hung up on numbers but pay attention to the authoring performance and efficiency of your project.

NOTE: Changes coming in Flare 4

The guidelines above will still be good to follow going forward, but the release of Flare version 4 will add some new flexibility to how people size their projects. One of the new capabilities in Flare 4 is the ability to use “Master Project Linking”. The concept is that you could create a master Flare project on a network share location and in this master project you can store any elements (CSS style sheets, snippet files, topics, templates, Master Pages, etc.) that you would like to be common across multiple smaller Flare projects. This will allow some of those huge 10 or 20 thousand topic projects out there to be broken into smaller projects and still never have to do the multiple edit thing. This Master Project Linking model creates a new library of shared components that can be used and re-used across as many Flare projects as you need.

For example, if you place your master CSS file in the Master Project on the network and then you link to it from 15 smaller Flare projects then you will have the same look and feel in all 15 projects. Then, if there is a need to update the styles you only update the style sheet once and your style changes automatically filter down to all 15 projects.

This will be adding an entirely new level of flexibility allowing teams to be able to plan their Flare project sizes around what is optimal for their particular team.

P.S. Before anybody asks, no we have not publicly announced an official Flare 4/Blaze ship date yet, but it is close enough that I felt it was important to include the above information for those who are doing project planning.

Moving documentation to XML – Just what does that mean?

This will be a long explanation, but there are quite a few elements that determine the success or failure of a new XML implementation so I want to be thorough. Some of this you may already know, but just in case I wanted to cover everything. 

A proper and valid XML work flow requires three things. First you need the “rules” file to control everything. The rules file is the SCHEMA file (or possibly a DTD for older XML implementations). The SCHEMA file is the final arbiter of just what constitutes a valid and legal file for a given publishing work flow. There are public SCHEMA files that can be adopted or custom/proprietary SCHEMA files can be written to a specific purpose. The first hurdle when creating a custom SCHEMA file is to make sure that a LOT of planning goes into its architecture. Once a SCHEMA file is written it is pretty much set in stone. The reason is that once you have started using a SCHEMA file the  documents you create with it are permanently locked to it. If at some point it is determined that the SCHEMA file needs to be updated there is a serious risk of rendering all previous documents created with it completely invalid and unusable. XML is a very unforgiving environment and it requires absolute precision. This is just one of the reasons that most companies choose to use publically available SCHEMA that have been tried and tested over time. 

Second, you then create your content files in accordance with the SCHEMA document. For a proper XML work flow you must be working on the native XML documents, not an intermediary format and doing conversion later. One misconception is that this means that the documents must have a .XML file extension. The reality is that valid XML documents can have any file extension as long as it fits within the work flow defined in the SCHEMA. You could have a file called document.fred and it could be a valid XML document. The important thing is that the contents of document.fred declare this document to be an XML document and completely and fully conform to the rules of the SCHEMA in place. 

Third, the part of the process that can be the trickiest and most expensive (and the most overlooked by teams adopting XML for the first time) is the transformation of the raw XML content files you have created into a format that the customer can use (PDF, Microsoft .CHM, web or browser-based systems, etc.). This step is one of the reasons that a lot of companies choose to use a SCHEMA that is already publicly available as this usually means that there will be pre-built transforms available to allow conversion of the raw documents into customer documents. If a team wants to build their own internal custom SCHEMA then a significant amount of budget needs to be allocated to this part of the process as it usually requires the services of programmers/developers and often more than one. The reason is that the creation of a custom XML transform requires that the person creating it is not only an absolute expert on the SCHEMA in use (and all legal combinations of elements within that SCHEMA and how to accommodate them during the transform process) but they also have to be an expert on the format being transformed into. As a result this tends to be a rather specialized field. You may need one developer to write a transform to create PDF and you may need a different developer with a different set of skills to write a transform to create Microsoft .chm files. This high level of expense deters many teams from writing a custom SCHEMA and adopting a tried and tested public SCHEMA instead.

 Those are the three pieces, SCHEMA (the rules), XML files (the content), Transformations (the conversion from raw XML to customer deliverables).

 What we do here at MadCap Software is adhere to all of the above rules AND include all of the transformations to the common output formats in a turn-key system. One of the items that is a little peculiar to our work flow is that we don’t use a single SCHEMA for validating our files, we actually use two SCHEMA files at the same time. For any visible content we validate against the W3C XHTML SCHEMA and for all of our content management/single-sourcing rules and meta-data we validate against a MadCap SCHEMA.

 Some wonder why we use the W3C XHTML schema at all? Why didn’t we just write an all encompassing MadCap Schema that did everything? Honestly, that would have been much easier for us but we wanted to create a work flow that never locked up our customers’ content in any proprietary manner. Since the W3C XHTML SCHEMA is the most commonly used XML SCHEMA on the planet it seemed an obvious choice for maximum content portability in the future. Since the XHTML SCHEMA contains no content management or single-sourcing capabilities at all we then augment it with the MadCap SCHEMA (called out in every file by name space, a fully legal and valid XML technique). This provides a best of all worlds solution, full support for state of the art single-source publishing, content that is never tied up in any proprietary manner, and a complete suite of built in transformations for creating the most common customer delivery formats without having to  hire a programmer.

 Hopefully this helps to dispel some of the XML myths I see floating around from time to time.

Comparing Documentation Server Software – MadCap Feedback Server and RoboHelp Server

I am often asked about our MadCap Feedback Server and what if any benefits it has over the older RoboHelp Server. Since I have been involved in development of the core architecture and capabilities of both I think I have a unique viewpoint on the subject (however, in full disclosure, remember that while I was part of the team that developed the RoboHelp Server architecture at Blue Sky Software I am now a competitor).

Overview

One of the key original functionalities included in the RoboHelp Server was a natural language search engine, but for some reason¹ Adobe removed that technology making the RoboHelp Server a “one trick pony”. While it has some minor additional features its main reason for existence now is to provide a limited set of “canned” feedback reports tracking customer usage. On the other hand the MadCap Feedback Server provides the same customer tracking capabilities but allows you to create an unlimited number of custom reports using a built in report and statistics generation engine. In addition the MadCap Feedback Server also contains a full Web 2.0 customer commenting capability allowing your customers to become part of the documentation process.

Another extremely important point is the consistency that MapCap Software builds into all of the different publishing formats supported. The same customer experience is available on the desktop experience (DotNet Help or Microsoft HTML Help), in the web browser (WebHelp), or from the MadCap Feedback Server (WebHelp Plus). For example, our Web 2.0 community commenting capabilities are available in every format listed above, even the desktop formats. With the current RoboHelp technology it seems that every different output generated has a radically different set of capabilities leaving the author to do an extreme amount of research to make sure that the features that they need will indeed be supported by the format they need to publish.

Capabilities

Search – The MadCap Software tools create content search capabilities that are far superior to anything available in the industry at a matching price point and greatly surpass the capabilities in the RoboHelp line.

Results Order: In older tools (including RoboHelp) search results are presented in an alphabetized list. This was easy to do within web browsers, but is not that helpful to the user. Imagine a set of Google search results that were alphabetized, how helpful would that be? No, the state of the art in search technology requires that the search results be relevancy ranked. To support this MadCap tools have implemented several ranking algorithms that provide a full relevancy ranked results list, much like a Google search, to the users. This is also done without any browser plug-ins or any other technology necessary. This helps your customers find the most relevant information as quickly as possible.

Synonyms: Both the MadCap and RoboHelp server technologies provide mechanisms for manually adding synonym support to the search capabilities (based on the tracking and usage reports). However, only the MadCap technology goes a huge step further and incorporates any hand built indexing data into the search parameters. If you have built a good index complete with synonym support, alternate phrasings, and commonly sought concepts, then all of this data is used to augment the search – automatically. This precludes the need to go back and manually enter a bunch of synonym data twice the way that RoboHelp forces you to do.  

Web 2.0 – The MadCap Feedback Server support for Web 2.0 community technologies is a complete turnkey system. Once installed there is nothing that your developers or programmers need to do to make this work. All that is required is for you to select the appropriate options while publishing your Flare projects to turn these capabilities on. In contrast, the few similar options that Adobe has introduced are limited to the Air output only (not available in the more popular WebHelp) and even then require either programmer/developer hours or Rube Goldberg-esque scenarios where data files have to be emailed back and forth between users.

Page Ratings: Any user can rate any page/topic from one to five stars showing how helpful that topic was to them. These user rankings are combined and averaged on the server and then displayed in the toolbar of the topic. At any time all users can see the overall quality ranking of any topic. With the MadCap Feedback Server technology this capability is available in all desktop and browser-based formats, which with Flare Version 4 will include a native option to build Air-based help. With RoboHelp technology, topic ratings are not available for browser-based or desktop formats and are only available with Air-based help. Even then, it requires programmer resources as this technology is not natively supported by the RoboHelp server.

Topic Comments: The MadCap Feedback Server provides the ability for any user to append their own comments at the bottom of any page if you allow them to. There are two levels of control. First who can post is controlled and you can choose to allow anonymous comments or you can require that commenter’s register first with a valid email address. Second, you can control the visibility of comments. You can set the system so that comments go live immediately or they have to be approved by you first. With the MadCap Feedback Server technology this capability is available in all desktop and browser-based formats, which with Flare Version 4 will include a native option to build Air-based help. With RoboHelp technology, comments are not available for browser-based or desktop formats and are only available with Air-based help. Even then, it requires programmer resources as this technology is not natively supported by the RoboHelp server.

Availability

The MadCap Feedback Server is available as either server software you purchase and install on your own hardware or as a hosted solution on our servers that you can contract. This hosting has proven quite popular both with small shops who don’t want to deal with server installs/maintenance and also with larger teams that want a short term contract with our hosting while they are in development and then switch to a purchased version when they go live with their project. This allows them to begin testing extremely early in the process. With the RoboHelp solution your only option is the software purchase. 

Architecture

The MadCap Feedback Server is built natively around the C#/.NET technologies to completely integrate into the server environment. The RoboHelp model was written in the older C++ language and then has a translation layer/wrapper written around it disguising this older core technology behind a .NET veneer. While this worked, it did result in some unintended consequences. Most people using the RoboHelp Server in a production environment with even medium loading find that they need to reboot the server at least weekly to keep the performance up. There are no such reboots necessary with the MadCap Feedback Server.

The RoboHelp Server also requires that the content files be stored on the very same machine as the RoboHelp Server. This means that you are locked in to putting everything on a Microsoft IIS server. In a MadCap Software tool work flow generated content files can be run on the same Microsoft IIS server as the MadCap Feedback Server, or your content files can be hosted on a single Unix or Linux machine or even on a farm of machines for load balancing. This can be critical for high traffic situations. It also comes in handy if your company is a Linux/Unix shop, you won’t have to explain why you need a bunch of new Microsoft servers just to host your documentation.

Summary

While the RoboHelp Server was good for its time (initially launched as the MindReader Server in 2001 by eHelp Corporation, formerly Blue Sky Software) its core architecture is out of date and in need of a complete re-write from the ground up using modern technologies and standards. On the other hand, the MadCap Feedback Server is an example of modern technologies implemented in a standards compliant manner allowing for maximum flexibility and reliability. Add to this the additional Web 2.0 community capabilities on top of the usage tracking/reporting capabilities and it is easy to see that MadCap Software is not only keeping pace with the state of the art in online documentation but is actually leading the industry into the future.

———————————————

(1) When Adobe removed the natural language search capabilities from the RoboHelp Server they claimed it was because nobody used it. What is interesting is that several months earlier I had recieved a phone call from a vendor claiming that I, as a representative of RoboHelp, owed them several years of back royalties for the natural language technology in use behind the RoboHelp Server. They had found my name associated with RoboHelp via a Google search. I informed them that since February of 2005 I had no part of the RoboHelp business but that it was now owned by Adobe. The other end of the conversation was something like, “Oh, really!” and then just a few months later Adobe announced the removal of natural language search from the server. Interesting.

STC Summit Update

Last night the trade show exhibit opened and today was the first full day of exhibits. It was great seeing old friends and making new ones but WOW were we busy!

As attendees entered the registration was on their left.

 

Once past the registration windows attendees found the entrance archway to the exhibit hall.

This year we did a full 20 foot by 20 foot booth to hopefully better handle the number of people that wanted to attend our demos and speak with our staff. The booth looked like:

 

 

 

 

 

 

 

This was definately a much bigger booth than we had last year. How did it work out at containing the crowds?

Well, we tried. ;0)

 

MadCap Software at the STC Summit in Philly

For those folks attending the STC Summit in Philadelphia make sure to swing by the exhibit hall and introduce yourself. We will have a full staff in attendance with representatives from sales, tech support, development, even executive management. Any possible question you might have for us, there will be someone in the booth who will have the answer.

It should be a great show. We are pulling out all of the stops as it were with a big 20 foot x 20 foot booth right at the exhibit hall entrance. We will have our in booth theatre up and running, we will have excellent take-aways (the usual t-shirts but this year we have added mouse-pads and even temporary tattoos for the adventurous), and five different prize draws throughout the show. The prize draws will be at the end of lunch and the end of exhibit hours each day and we will be giving away hundreds and hundreds of dollars worth of software at each prize draw so don’t miss them!

 This show will also be the official unveiling of our “rogue writer” logo gear, with the obligatory propeller. We will have a limited number of t-shirts and mouse-pads with this new logo, and even temporary tattoos of it as well. This was meant to be a bit of a gag but based on early feedback I think this gear is going to be far more popular than we anticipated so if you want something with the “rogue writer” graphic on it you should probably get to the booth early in the show.

Below I have also included the full schedule for the topics being covered in the booth theatre for those who want to start planning their STC game plan early.

MadCap in Booth Presentation Schedule

Monday, June 2 (Exhibit Hall Open 10:30-7:00)

       Time         Location             Topic
10:50 – 11:10    MadCap   Topic-based Authoring – The Key to 
                           Booth      Advanced Single-sourcing
                                          Sharon Burton, Product Manager

11:35 – 11:55    MadCap   MadCap Software – Complete Product 
                           Booth      Line Overview
                                          Mike Hamilton, V.P. Product Management

  1:35 – 1:55     MadCap     Top Five Features of MadCap Flare –
                          Booth        Through the Eyes of a Technical Writer
                                           Paul Stoecklein, Senior Technical Writer

  3:05 – 3:25     MadCap     MadCap Lingo Demo – 
                          Booth        Translation and Localization 
                                           Mike Hamilton, V.P. Product Management

  3:50 – 4:10     MadCap     MadCap Mimic Demo – Quick Tour
                          Booth        Patricia Dear, Product Manager

4:35 – 4:55      MadCap      MadCap Analyzer – 
                         Booth         Content Analysis in Real Time
                                           Neil Perlin, Industry Expert/Certified Trainer

 6:35 – 6:55     MadCap     MadCap Flare Demo – XML-based 
                         Booth        Authoring and Publishing  
                                          Mike Hamilton, V.P. Product Management

——————————————————–
Tuesday, June 3 (Exhibit Hall Open 9:00-6:00)

     Time            Location                     Topic
10:05 – 10:25    MadCap    MadCap Analyzer Demo – 
                           Booth       Automated Content Analysis and Validation
                                           Sharon Burton, Product Manager

10:30 – 11:30    Room       Advanced Print Publishing with 
                          109B        MadCap Flare
                                          Mike Hamilton, V.P. Product Management

11:35 – 11:55   MadCap     Sharing Variables Between Flare and Mimic:
                          Booth       Single-source Publishing Across Media Types
                                          Neil Perlin, Industry Expert/Certified Trainer

 2:35 – 2:55     MadCap      MadCap Software – Complete Product 
                         Booth         Line Overview
                                           Mike Hamilton, V.P. Product Management

  4:05 – 4:25    MadCap     MadCap Flare Demo – XML-based 
                         Booth        Authoring and Publishing
                                          Mike Hamilton, V.P. Product Management

 5:35 – 5:55    MadCap     Cross References – 
                        Booth        Putting Your Links on Steroids
                                         Paul Stoecklein, Senior Technical Writer
———————————————————-
Wednesday, June 4 (Exhibit Hall Open 9:00-1:15)

       Time        Location               Topic
10:05 – 10:25   MadCap    MadCap Blaze Demo – 
                         Booth        Advanced, Topic-based, Print Publishing
                                          Sharon Burton, Product Manager

11:35 – 11:55   MadCap    MadCap Software – Complete Product 
                          Booth       Line Overview
                                          Mike Hamilton, V.P. Product Management

 

 

 

Flare WebHelp Running On Windows Mobile 6

Every now and then I stumble onto something that really excites me. Today was one of those days.

Folks who know me know that I am a mobile device nut. Well, today I received an invitation to participate in a beta program for a new Windows Mobile 6 compatible browser called SkyFire http://www.skyfire.com/ .

 

It is a neat new concept for mobile browsers as it renders the entire page just as you would see it on a desktop and then allows you to zoom in to read the text. I was hopping around the Internet checking various sites and then I gave the MadCap Software home page a try and it rendered beautifully. Even the short movie at the top of the page animated properly. This really is a great new mini-browser. Then I got an idea. What about the tech support Knowledge Base that was published in WebHelp format? I pointed skyfire at the url and it loaded beautifully!

 Then I tapped over the WebHelp TOC (Table of Contents) and a little zoom marker appeared.

Clicking again on the zoom marker zoomed directly in on the WebHelp TOC allowing me to open/close books and select a topic.

I was then able to drag the screen to scroll around and read the topic.

 Now, I realize that this may not be the most exciting thing, but remember, this knowledge base was designed and built for a large desktop browser. Imagine creating a custom MadCap Flare Skin file optimized for this smaller screen size. For the first time fully interactive document access of a system of potentially thousands of pages of content with integrated search, table of contents, index, etc. all in the palm of your hand!

The folks working on skyfire are doing some pretty cool work and I will be spending some time figuring out how to best leverage this new browser for documentation purposes. My apologies if some of the screen shots above ended up a little “crunchy”, I assure you they looked pretty darn good before the jpeg compression. Just in case, I recorded a short little video of the process in case it helps to show things in a more meaningful manner than my excited ramblings.