Tag Archives: online help

adobe, amazon, professional, sharepoint, web authoring

What next for application help and documentation? First thoughts on Adobe’s Technical Communication Suite 3

Adobe has launched Technical Communication Suite 3, which bundles FrameMaker 10, RoboHelp 9, Captivate 5, Photoshop CS5 and Acrobat X. FrameMaker and RoboHelp are Windows-only, so the suite is the same.

I had a brief briefing on the product today, which by coincidence came after my bad experience with SharePoint Designer and its help system. Please note: I do not hold Adobe responsible for the shortcomings of Microsoft’s online help, but it helped me to put the subject into context. I was trying to figure out how to get SharePoint to display file extensions in document lists. The supplied help looks pretty:

image

but I found it disappointing. I wanted to know, for example, what are the implications of converting a web part to XSLT, which is on one of the designer context menus:

image

Same story when I wanted to know what the @LinkFileName formula was meant to return. And when I looked for a SharePoint formula reference I got one useless result, an article on creating a workflow initiation form.

What we all do in these situations is to hit Google. The snag: whereas the little online help (which is also meant to search Office online) had high authority but no results, Google has the opposite problem: many results but little authority. I did eventually find the formula reference I wanted but finding correct information on the web as a whole is a matter of luck and judgment.

I found it interesting therefore to talk to Adobe about its Technical Communication Suite. How is online help changing? Do we even need it, when people hit Google rather than F1? Maybe it is better just to make sure your help articles and reference are easy to find on the web, rather than packaging them up and calling it a help document? In which case, we should be thinking in terms of a content management system, rather than online help as such.

The answer I guess is “all of these”. The key concept in Adobe Technical Communication Suite is “single-source authoring”, and you can use the same content for web pages as well as for print and traditional packaged online help.

It is still a bit old-school for my taste. For example, you can now include External content search in RoboHelp documents; but this only lets you add external URLS to the document along with search keywords. It does not let you search external content, but restricted to specified web sites, which would be a nice feature.

That said, if you use RoboHelp Server 9 – not included with the suite itself – in conjunction with an Adobe AIR help client, you can get user topic rating and commenting, so there is some concession to user-generated content.

There are also plenty of scenarios where you do still need a blow-by-blow documentation and reference for an application. In fact, if the SharePoint help mentioned above had provided this, I would have been happy.

This is not a review of the Technical Communication Suite, though I hope to get a look at the actual product shortly. In the meantime, a few points of interest. FrameMaker has considerable feature overlap with InDesign; but Adobe says there is still a place for a desktop publishing tool aimed at long technical documents with strong support for structured documents, cross-references and indexes. RoboHelp now supports collobaration workflows using Acrobat.com and PDF review. There is also new support for ePub, the eBook format for everything but Amazon Kindle, in FrameMaker and Kindle. I asked about Kindle support; the Adobe spokesperson was sniffy about Amazon’s proprietary MOBI format but said it might be added eventually if Amazon do not add ePub compatibility to the Kindle.

.net, microsoft, visual studio

Visual Studio 2010 testers unhappy with help

18 Comments

Visual Studio 2010 comes with a brand new help system, based on a local help server rather than a database plus viewer as in the past. There is also an option to use Internet-based help for the most up to date content.

Sounds good, but developers are not happy. The problem: the new help appears to have no index of contents. You are meant to navigate by search, then perhaps navigate forward and back using the table of contents tree that appears on the left.

image

In the old one, you could use the index to find keywords quickly:

image

It turns out that many users prefer the old approach:

This is terrible. Productivity will go to zero without an index. Online help is junk, even on a fast connection — it can never be as fast as my local PC and when I am programming, I need instant answers.

says one commenter.

Microsoft says:

We realize the importance of delivering a keyword index, but we were unable to deliver it in our first release. In this V1.0 release of help system, we first implemented an improved search capability in order to deliver a more familiar, consistent online and offline experience. We then implemented a keyword index feature based on our search catalog. Unfortunately, the results did not meet our quality bar and we determined that this feature would require more work than the Beta 2 timeline allowed. We are looking at implementing it for at future release.

The odd thing is, there is a third-party viewer called H3Viewer which was apparently put together in a short time using Delphi and the new APIs. It turns out that Visual Studio’s Help is actually an early example of a new Windows Help System called Help 3, and is designed with a comprehensive API for developers. If you set the default help viewer in Visual Studio 2010 to H3Viewer, it works more like the old one, complete with index:

image

I can’t actually recommend H3Viewer in the current  beta. It takes ages to read 440,000 index entries every time you start it up and view the index pane – a message notes that “a late fix in the RC release has slowed down the reading of index items dramatically”. In addition, it does not cope well if you set your help preference to online. Still, H3Viewer will likely improve.

Speaking personally, I don’t mind the idea of search-based help, provided that the search works really well. In practice, it is often easier to Google for what you want to know, bypassing the official help completely, though that may mean getting to the same place by another route. Nevertheless, a reliable online reference is important and it seems that a lot of developers do in fact use the local index.