Category Archives: Doc-To-Help

Doc-To-Help

Pardon the Introduction…

2015 is going to be an exciting year.

MadCap-D2H

With all of the activity going on around here at MadCap Software, I wanted to take a moment to introduce some resources that are now available to the Doc-To-Help community – your product evangelists!

Michael Hamilton

VP of Product Evangelism

“MadCap Mike” has over fifteen years of experience in training, technical communication, multimedia development, and software development. Prior to joining MadCap Software, he served as the Product Manager for Macromedia’s award-winning RoboHelp product line. Mr. Hamilton is often a featured speaker at industry events, including TEKOM, LavaCon, and STC.

Jose Sermeno

Product Evangelist

With over 10 years of experience in the software industry, “MadCap Jose” brings a wealth of knowledge and expertise to the product evangelist team, helping introduce new users to everything MadCap Software. In his spare time, Jose is an organizer for the San Diego Mini Maker Faire, and a mentor for San Diego City Robotics, the San Diego community college systems robotics program.

How Can We Help?

As product evangelists for MadCap Software we’re involved in many aspects of TechComm, and are able to assist you and your team in a variety of ways.  Product and workflow demonstrations, technology or process questions, integration discussions, and really any time you’re just unsure of how to proceed.  Please feel free to reach out to us via Twitter or our other MadCap / Doc-To-Help social media channels!

Twitter:

@MadCapMike

@MadCapJose

@MadCapSoftware

@MadCapDocTeam

Facebook:

www.facebook.com/MadCapSoftware

www.facebook.com/DocToHelp

YouTube:

www.youtube.com/MadCapSoftware

www.youtube.com/DocToHelpTV

LinkedIn:

www.linkedin.com/groups/Users-DocToHelp

www.linkedin.com/groups/Users-MadCap-Flare

I hope you are as excited as we are to welcome you to the MadCap Software community of users, resources and product evangelists. Be sure to stay tuned for additional announcements including new free live webinars and session updates for MadWorld 2015.

Search Engine Optimization and Technical Documentation

How good is your documentation if no one can find it? What if your users don’t remember its location or do not want to weed through pages of documentation to find the information they are looking for? To ensure your users can readily find the information they are seeking, your documentation needs to be optimized for searching.

Search Engine Optimization (SEO) refers to the tactics that can improve your search engine results. That is, it influences how early in the search results you will find a website. SEO not only considers how each search engine works (as each one operates differently), but also how users search for the information. By utilizing SEO in your technical documentation, the specific topic that each user is searching for will be more easily found. Therefore, even if you are not concerned with how your documentation is ranked by Google, Bing, or whomever, you should still consider the various factors that impact SEO.

SEO Tactic: Add Search Terms

First and foremost, optimize your documentation with your users’ search terms. That does not mean riddle your documentation with these keyword phrases, nor does it mean you should bold or italicize them. The search terms need to exist in the relevant documentation page at least three times – that’s all you really need. That is such a small amount that it will likely exist naturally without you having to think too much about it.

Search Terms in Tags

Search engines will also look at the title tags and anchor text (i.e. the visible text in a hyperlink) for keyword phrases. These are automatically added into your Doc-To-Help output by creating title tags based on the topic names, and including related topic links (aka subtopic links) within the content.

To take this a step further, search engines also examine the terms found within the heading tags (i.e. the visible headings found on a website), with <h1> carrying the most weight to <h6> having the least. Doc-To-Help upholds this side of SEO by automatically utilizing these tags when the Heading Styles are specified in your documentation.

Therefore, if you find that your users are constantly searching for something like “how to do process X”, then make that your topic title or heading, and it will become easier to locate. Additionally, avoid ambiguous titles and headings such as “Introduction” or “Phase II”.  For instance, include the product name and more informative text such as “Product X: Introduction” or “Product X: Phase II Rollout Plan”.  By doing so, the relevant pages will be more findable than if a generic title or heading was used.

Search Terms in Your Media

Search engines do not utilize Optical Character Recognition (OCR) to translate the characters found in images and videos into text. Although media can have visible text, it is completely ignored by search engines without utilizing captions since they do not use OCR. Adding meaningful captions to your images and videos also gives you an opportunity to add relevant search terms to your documentation. But, don’t try to force these keyword phrases into the captions – ensure the captions are still pertinent.

Identifying the Search Terms

With Doc-To-Help, adding the specific search terms to your documentation is pretty easy. However, identifying the search terms can be very challenging. With the introduction of Nest Server, optimizing your documentation for searching will become much easier.

Nest Server will allow you to see what specific keyword phrases your users are searching for and how often. You will also be able to see these search terms’ rankings within specific date ranges, allowing you to correlate search phrases with product releases, changes in processes and so forth.

SEO Tactic: Add Links

The second factor that can impact SEO are links. As mentioned, anchor text can positively influence your rankings. These internal links automatically created with Doc-To-Help help users and search engines to better crawl through your documentation.

Also, Google and other search engines’ algorithms are heavily based on backlinks (i.e. the links pointing back to a particular webpage), making them imperative to SEO. Therefore, if your documentation is on a different domain than your company’s website, you should consider adding links from your company’s website back to your documentation (and vice-versa) to improve SEO.  In addition, you should consider adding links to your documentation from your company’s social media sites.

Canonical links can further impact SEO. Canonical links specify a preferred URL if duplicate sites are found. For instance, if you have different versions of Help documentation available, the canonical link will specify the URL, or the preferred Help documentation version, returned in the search results.

SEO Tactic: Use Word-Friendly URLs

Third, the structure of your documentation’s URLs can impact SEO. URLs can be obscure and complicated as seen below:

www.example.com/product/2014/369-54321-2014a?v=glance

On the other hand, you can also create word-friendly URLs such as:

http://www.doctohelp.com/Products/DocToHelp/

As you can see, having word-friendly URLs makes it easier for users to understand where they are going, and are a lot easier to memorize.  With Doc-To-Help, word-friendly URLs are automatically created for you based on the topics.

Word-friendly URLs have a positive impact on a website’s Click-Through Rate (CTR).  That is, you will increase your chances of users clicking on a link to your documentation.  By having word-friendly URLs, you are also increasing the chances of others adding backlinks on their websites to your documentation.  As discussed, backlinks created to your documentation will boost search engine rankings.  Plus, having word-friendly URLs reduces the risk of user error when creating these backlinks.

Moreover, having word-friendly URLs boosts the ability for search engines to crawl through your documentation.  The ease of navigation can help search engines understand what content you feel is important.  Also, these crawlers identify the words used in the URLs as key search terms.

SEO Tactic: Avoid Frames and Making Certain Changes

Finally, there are things that can hurt your rankings. Utilizing frames or iframes in your documentation will negatively impact search engine results. There are many help authoring tools that utilize frames and iframes in their web-based output, but Doc-To-Help does not.

Note: If you are on Doc-To-Help version 2011 or older, the original NetHelp output (currently called NetHelp Classic), does utilize frames. If you upgrade to the latest version and rebuild, your NetHelp output will no longer contain frames, and you will avoid negatively impacting your SEO altogether.

Additionally, there are particular changes that can negatively impact SEO, which include changing a webpage’s URL, the hosting server’s IP address, or any links. If you make such changes, it could take months for the various search engines to reindex your documentation. Until it is reindexed, the website could have a lower ranking than before these changes took place.  Also, changing your URL could also cause the backlinks to your site to break, thereby hurting your rankings even more.

This is not meant to be a recommendation to avoid updating your content – just make changes to links, URLs, and addresses sparingly. In fact, if you find that a lot of users are reading about specific topics, these are good areas to routinely focus your attention on to ensure they are properly maintained.

Simply Easy to Optimize

If you keep these factors in mind and with a tool like Doc-To-Help, you can seamlessly implement SEO into your documentation. By doing so, you will see major benefits such as improving the ability for your users to more readily find the answers to their questions.  In turn, this can reduce support requests, and in so doing reducing costs.

Keep in mind that the algorithms used by search engines to identify and rank each website are very complex and are continuously evolving to stay competitive.  With that being said, there are other factors that can impact SEO.  However, the ones mentioned above are consistently used across all of the main search engines and each have a major impact on SEO.

If you have any questions on how to implement SEO into your documentation, feel free to email me at shani.mahler@componentone.com or leave a comment.

System Operations Company Implements Comprehensive Online Content and Training Guide System Using Doc-To-Help

Georgia System Operations Corporation (GSOC), an operation that manages electricity demands from generation to transmission, relies heavily on technical documentation for their data systems. The technical documentation team in the systems and settlements department at GSOC was tasked with developing the company’s online user and training guides.

In conjunction with the software development team at GSOC, the documentation team set out to find a way to create and manage online content that is easily accessible by all company employees. Once GSOC identified their top priority projects they researched tools that would help them produce the documentation they needed. After researching the technical communication industry, GSOC chose Doc-To-Help, a popular solution for publishing professional-quality user manuals and Help systems, as it provided the integrations GSOC needed for their projects.

The first project using Doc-To-Help that GSOC created was a web based Data Portal that provides data reports and interactive workflow processes, and uses a database platform for managing user membership and report data. The browser-based Help system, hosted on SharePoint, features a large interactive Glossary that informs new users of proprietary company terminology, and a library of images that illustrate a variety of Data Portal functions. Doreen Marson, a technical documentation specialist at GSOC stated that, “The Data Portal’s Help was being handled manually and contributing subject matter experts from various departments were maintaining their own hard copy manuals.”

“By using Doc-To-Help, Help now is integrated into the application. Thanks to Doc-To-Help we now have a centralized approach for managing all Data Portal Help Content (manual, user guide, procedures, etc.) generated by document creators/SMES from various departments,” said Marson. “This lessens the possibility that required updates are missed or that outdated information remains within that content. Content is consistent across the companies’ groups and departments. Plus, the entire Data Portal Online Help is single-sourced using Doc-To-Help, allowing GSOC’s technical documentation team to author in Microsoft Word, manage project reviews using SharePoint, and publish to a SharePoint web server, PDF, and Help for mobile devices.”

Next on the project list was to create an Image Library to illustrate a variety of GDP functions. GSOC was finding it difficult to maintain and update images, plus it was hard to manage them separately across projects. With Doc-To-Help’s use of file naming by Data Portal topic names and keywords, GSOC created a new linked library which saves screen real estate, reuses content (across all Doc-To-Help builds), and optimizes the project for mobile. Marson shared that, “As the image library grows, we’ve gained the ability to differentiate them further and are reaping the benefits of having a carefully planned image library structure.”

After the Image Library, GSOC set out to develop and implement a company-wide utility industry glossary of terms, drawn from many sources to promote group understanding of acronyms, terms and definitions to be used throughout the Family of companies. It was formerly maintained as a series of paper documents, separately updated by each company. By using Doc-To-Help for this project, GSOC was able create a single source glossary that is now searchable and updated online, transparently to the Members and Associates. The glossary integrates with other Doc-To-Help projects and is also accessible standalone. “Company executives and employees were pleased that all remote sites can now access the glossary and it is always up to date,” said Marson.

The final of the four main projects, was to develop and implement a robust content management process in Doc-To-Help. The goal was to help users find content they needed from various proprietary applications using an existing Doc-To-Help project for content integration and mapping and SharePoint Document Library for workflows and source control. The problem that had to be addressed was that employees did not know what applications and processes existed within the company. It was solved through the creation of the member portal which serves as the central interface for all of these applications and sites. Users can now browse or search through a list of content topics from various applications and sites.

With so many of the features of Doc-To-Help being used in various ways, GSOC is leveraging all of Doc-To-Help’s strengths to make their work flow run smoothly and to improve their documentation. Marson shared that, “Our documentation has improved immensely. I came out of an environment where we used Word, Visio and PowerPoint and there was never any collaboration between them, and the navigations were never easy. With Doc-To-Help the navigation is there and I use NetHelp, which gives us a more browser-based look and feel.”

Most recently GSOC has been creating new designs and themes. They have been able to use Doc-To-Help’s Theme Designer to style the “skin” that surrounds their online Help content. With several of the pre-defined themes that are included for each Target in Doc-To-Help, GSOC has found it easy to find the theme perfect for their needs.

GSOC plans to next take advantage of Doc-To-Help’s latest feature, the ability to automatically generate outputs with features that would otherwise require advanced development skills. GSOC, like many other companies, is moving quickly toward mobile platforms. Marson noted that she has the upper hand because Doc-To-Help will automatically generate Responsive NetHelp, a web-based output that automatically adjusts itself to screen size. “I am not a developer, so that is a huge help,” said Marson.

Doc-To-Help has truly created the most comprehensive product to serve all devices and platforms, thus avoiding the need to maintain individual sites while saving bandwidth,” said Marson. “If you can master Word you can easily use Doc-To-Help.”

Download a PDF of this case study.

Frequently Asked Questions in DocToHelp – Part III

Here in this part of our FAQ series, let’s discuss two generic problems that arise while using DocToHelp:

  1. Executing the Modular TOC Utility in an unattended batch operation
  2. HTML help (chm file) displays XML source code

Executing Modular TOC Utility in Unattended Batch Operation

Problem statement

The problem here is to run the Modular TOC Utility in an unattended batch operation. The need arises from the fact that we have several help-projects and a master-help file. We need this to work so that opening one of the chm-files will show the TOC of every help file. This is what the Modular TOC Utility does by modifying every hpp-file and the master hhc-file when running through the commands “Process Modules, Compile Selected Modules, Compile hub module and Compile all modules” on a previously generated master.hub-file.  We would like to do this in an unattended batch build so as to make things easier.

Solution

In order to accomplish this requirement, we would need to use the new version of the ModularTOC utility which can be downloaded from here.

Note- The previous version of ModularTOC.exe which is usually located at the following place on one’s machine must be backed up and replaced with the new one:
“C:\Program Files (x86)\ComponentOne\DocToHelp\ModularTOCUtility\ModularTOC.exe”

To run the utility in batch mode, execute the following command:
ModularTOC.exe -fix “path-to-hub-file”

HTML Help (chm file) Displays XML Source Code

Problem Statement

When HTML Help generated by DocToHelp is opened on any specific machine then it displays XML source code instead of the original help file. However, the same chm opens correctly on other machines.

Solution

This is caused by something breaking part of the .htm file type in the system’s registry. Microsoft’s HTML Help components will go wrong if a particular registry value is set incorrectly.

Automatic fix
You can fix this by double-clicking the .reg file within archive: HTML_Fix_ContentType

Manual fix
In this case, you can edit the registry by hand. This assumes familiarity with RegEdit.exe.

  1. Go to HKEY_LOCAL_MACHINE\Software\Classes\.htm
  2. Ensure there is a Content Type value with Type = REG_SZ (String), and Data = text/html
  3. Go to HKEY_CURRENT_USER\Software\Classes\.htm
  4. If there is no .htm key at that path, or there is one but it has no Content Type value, you are done and can stop.
  5. Otherwise, ensure it is set to text/html as with the HKEY_LOCAL_MACHINE one.

Multiple Users
If the machine has multiple user accounts, you may need to apply the HKEY_CURRENT_USER part of the fix to each account separately.

Conclusion

This concludes third part of our FAQ Series.

Please share your comments and feedbacks on the solutions discussed. In case if you have any specific problem that you would like us to discuss in our next blog, let us know.

Get Social: Adding Twitter and Facebook Buttons to NetHelp

(Note: This functionality is available starting with 2014 V1, which you can download here.)

With more and more users of Facebook and Twitter mixing their work lives and private lives on social networks, giving these users the ability to share your online content with their network increases the amplification and visibility of your NetHelp outputs.

The Responsive theme already includes Twitter and Facebook buttons on the NetHelp toolbar by default. If you’re looking to go the Responsive route, choose that theme from the Theme dropdown, build and deploy your NetHelp and you’re done.

If you use the Tabs or Accordion themes (or a custom theme based on one of those themes), adding the Facebook and Twitter buttons to your NetHelp toolbar is as easy as clicking a button. These social media buttons have been added to Tabs and Accordion themes by default and all themes based on those default themes will automatically. All you need to do is click the Theme button on the Home tab and click Yes when Doc-To-Help asks you if you want to upgrade your theme to the latest version:

Click Yes to upgrade your Theme

Click Yes to upgrade your Theme

The next time you build, both buttons will be available in your NetHelp toolbar:

FacebookAndTwitterButtons

Users can click the button and share a direct link to the active topic with their networks. This will also work with your company’s Facebook and Twitter accounts, if you have a daily topic or section in the documentation that you would like to share with them.

Upgrade to 2014 V1, upgrade your Theme, and start sharing today!