Tag Archives: Doc-To-Help

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!

Don’t Overlook the Importance of Text Width

We all love our bright and beautiful wide screens on our monitors, laptops, and even mobile devices, but they have created a new problem for communicators: text width. You can write the most expertly crafted content and ruin it if you overlook the behavior of text as screen size grows. Your paragraphs may look nice on your screen, at your browser size, but what happens when the browser is maximized or what if your reader is using a screen larger than yours? It can stretch out and become unreadable. Too many words per line can cause reader fatigue and fatigued readers give up. This is not only a readability issue, it can be considered a usability issue. You can also consider this a responsive design issue. In other words, it is important, so let’s not overlook it.

This article discusses text width, gives some advice on general style techniques, and shows how you can control text width in Doc-To-Help 2014 v1.

Live Comparison

Let’s start by looking at a simple comparison. There are two online Help systems linked and pictured below. Either visit the links and view them full screen or just look at the screen shots. The first has no constraint on text width. The second is constrained to 600 pixels. Which one do you think is more readable?

NetHelp with Full-Width Text

Visit the live sample.

NetHelp with full width text.

NetHelp with full width text.

NetHelp with Text Constrained to 600 Pixels

Visit the live sample.

NetHelp with text width constrained to 600 pixels.

NetHelp with text width constrained to 600 pixels.

Seems simple, but the difference is significant.

Layout Principles

It helps to see the technical thinking behind the concept. Go to Google and search something like “Optimal text width for the web” or “best line width for text” and you will see a collection of articles that repeat the sample two rules, which are backed by print layout standards.

  • About 50 to 75 words per line.
  • About 100 characters per line.

Studies show that anything beyond the above causes reader fatigue and, as I said at the beginning, that causes people to stop reading.

There are problems with these rules, though. There isn’t a style setting for word and character count and optimal line length depends on things like font size and the layout of the rest of the page.

The easy way to apply these principles to online content is to use a pixel width for your paragraphs. The rules above translate to roughly 600 pixels. This doesn’t mean you need to restrict the width of your entire site to 600 pixels, just text paragraphs. Images and tables can even go beyond that length. You just want to keep the reader engaged with the text.

By the way, modern Web design principles dictate that websites should be viewable at a 960 pixel total width. This ensures that they will look nice on small screens. That fits nicely with our text width rule. That gives you 360 pixels for other elements such as sidebars.

Applying the Principle to CSS

I have convinced you to constrain your text, now I should tell you how. The good news is that it is really easy. You just need to use the CSS width attribute in the tags you use to markup text — typically <p>, <span>, or <div> — like so:

p {
     width: 600px;
}

It is that easy. Of course, I have generalized it. The width attribute will probably be one of many, you may want to use it in a special calls, or you may prefer to apply it to a specific class, but you get the idea.

Setting Text Width in Doc-To-Help

Starting in version 2014 v1, Doc-To-Help’s Theme Designer has a text width setting. All you need to do is enter your desired width and Doc-To-Help will change the style sheet for you. Quick instructions follow. Remember, to change theme settings you need to create a new Theme. Doc-To-Help requires this in order to preserve the base themes.

Start by dropping down the Theme list on the Home tab of the ribbon and select your theme.

Opening the Theme Designer

Opening the Theme Designer

When the Theme Designer opens, you should see Text Width as the third setting under Topic settings. Enter your pixel width there and Doc-To-Help will do the rest.

Setting Text Width

Setting Text Width

As always, feel free to comment if you have questions.

What’s New in Doc-To-Help 2013 V2

(Don’t just read the blog post, download Doc-To-Help, and see for yourself.)

The Doc-To-Help team is pleased to announce the release of 2013 V2!

When we announced our 2013 roadmap as part of the general 2013 ComponentOne Roadmap, we outlined that the plan for 2013 was, “to focus on two major areas: enhancing the editing experience and making sure you are provided the best web-based reading experience possible.”

When we released 2013 V1 in May, the focus was on editing more than web outputs. We introduced the first HTML5 editor in the industry and added a number of other enhancements to Doc-To-Help’s content editor, including the ability to add comments giving you a number of options in Source mode.

The 2013 V2 release focuses more on the output side of things, with the splash feature of the release being the new Responsive Theme for NetHelp. Responsive design reads the display size of the device it is being viewed on and changes its appearance/style sheet accordingly, adjusting the interface that the user sees. Different users on different devices — a user with a laptop would see a different NetHelp interface than a tablet user and a tablet user would see a different view than a smartphone user — will have the content optimized for them automatically.

The benefit of Responsive NetHelp is that you can deploy your content once and your users will automatically see the best interface for their device, no matter what they’re using to experience the content. You won’t need to deploy multiple outputs for multiple devices and your users won’t need to be re-directed or need to hunt down those multiple deployments if they get to the documentation and realize it’s not optimized for their device. In effect, you can get all the birds with one stone (or deployment).

Read why Responsive Design is important.

On the content editing side, we’re rolling out Content Widgets in this release. Content Widgets are blocks of pre-made, editable, interactive content that you can insert in your source files in the HTML5 content editor.

Check out the Widget Explorer sample.

So, they’re really an enhancement for the editing (input) environment and deliverable (output) environment. All in all, it’s a major step forward for the product and a number of great features for Doc-To-Help users (new and existing) to test drive.

Take a look at 2013 V2 by downloading it today and letting us know what you think!

The Power of Responsive Design

Adopting a responsive design for our content truly “frees our content” to work anywhere, anytime. As technical communicators, we no longer need to spend time designing and creating deliverables for different devices. Instead, we can focus on developing and delivering the content our customers need. The right content, in the right place, at the right time.

Technically, responsive design is “Responsive WEB design”, so we must deliver our help to the web to take advantage of all that responsive design has to offer. But this is nothing new for technical communicators, since many of us have been delivering web-based help systems for many years, and mobile help for a shorter time. Providing a single responsive output gives us the opportunity to create once and deliver to thousands of devices: new ones, older ones – even ones that don’t exist yet.

Please note – it is important to understand the power of responsive design and how it works, but it isn’t necessary for technical communicators to code responsive outputs ourselves. Doc-To-Help gives us the power to build responsive outputs right out-of-the-box (plus do some customizations if we want to – see “All You Need to Know About Responsive NetHelp”). This means that, instead of coding, we can concentrate our efforts on optimizing our content for mobile.

Why the Time is Right for Responsive

  • Mashable has declared 2013 the “year of responsive web design” and notes that while tablet sales are expected to top 100 million in 2013, 2012 marked the first time in 11 years that PC sales did not top the sales of the previous year. 

A (Very) Short Introduction to Responsive Design

Responsive web design is a technique for designing web pages that automatically adjust to the device accessing them. A variety of technologies are used, the core ones being media queries, fluid layouts, and flexible images. The HTML code of the page never changes, but its presentation adjusts based on the CSS rules specified for the device/browser. No content is lost in responsive design; the content and the page layout simply adjust by stacking or collapsing. (There is no horizontal scroll bar.) There are other adjustments too: images will automatically resize and tables may reflow. In addition, pages may switch from touch interaction to mouse/keyboard interaction depending on the device.

Here is what Doc-To-Help’s Responsive Design looks like. On smaller screens (or when you resize the browser) the Table of Contents and the toolbar collapses. Clicking a button will display either.

Here’s what it looks like on the desktop…

Responsive Desktop

… and here is how it looks on a Mobile device. The TOC and toolbar buttons can be accessed using the buttons on the top right and left.

Responsive Mobile

You can test out a live version here:  http://showme.doctohelp.com/widgetexplorer/

In addition to HTML and CSS, jQuery, JavaScript, and sometimes PHP are used to create responsive designs.

Examples of Responsive Websites:

Best Practices for Technical Communicators

Creating responsive outputs means that technical communicators need to adopt a “mobile first” mindset – our content needs to be designed to work well on mobile (smaller) screens, because when you write/make other changes for mobile, then the content will work well on tablets, the desktop, etc.

A few “Mobile First” best practices; some technical, some content changes:

  • Keep image files small. Large image files will increase load time, which is something mobile users have no patience for, in fact, 74% of mobile users will leave a website that takes more than 5 seconds to load. http://www.sitepoint.com/4-common-responsive-web-design-pitfalls/
  • Concise writing. Always an excellent best practice, but now more important than ever. And this isn’t just about screen size; those working on smaller devices have less patience to wade through content. (Another benefit: this also reduces translation costs.)
  • Employ progressive information disclosure. This will make information easier to find, and puts the choice to learn more in the hands of the reader. Using collapsible text and inline text (dynamic help features) can be good solutions.
  • Improve navigation. Add related links at the end of topics so no one needs to use the device’s “back” button, because that makes it is easier to navigate away from your content.
  • Make links easier to use. Don’t bury too many in the same paragraph because they will be harder to use on mobile devices. Consider making the most important links into buttons.
  • Streamline your table of contents. A TOC that is 4-5 levels deep is more challenging to navigate on mobile devices.
  • Avoid second, third, etc. level bullets and numbering. It is harder to see the relationships between levels on smaller devices.
  • Take a look at your tables. Some of them may have too many columns and be very lengthy. Simplify them, and eliminate the ones that aren’t necessary. You can take advantage of responsive table reflow, but you will want to verify that your tables are usable on smaller devices.
  • Clean up your terminology. Your content needs to work on devices where you tap, and those where you click. Avoid using device-specific terms.

Additional Resources

The following two books and tutorial are excellent resources to learn more about RWD:

Responsive NetHelp: One Stone, All the Birds

When the need for small screen compatible Help first became apparent, we tapped into our jQuery Mobile expertise (Wijmo is our sister product and is full of web development goodness) and a new output called Mobile Help soon followed. Mobile Help was a version of NetHelp designed specifically for phones and tablets. If you wanted Help for these devices, you would produce Mobile Help and if you wanted your readers to use desktop browsers, you would produce traditional NetHelp. While that is easy, our customers still needed to produce and host two versions of Help. (A “two stone” method.)

Enter Responsive Design. Responsive Design is a concept that designers and developers follow to make their Web pages automatically adapt, or respond, to the size of screen it is loaded on. For example, a left-side menu may be always present on a large screen, but collapse on a phone. Other things, such as automatic image resizing and table reflow, can also happen. This concept isn’t limited to layout; pages can automatically switch to touch interaction on small screens and then revert back to mouse and keyboard on large screens.

In December, we will release a version of NetHelp called “Responsive NetHelp” and this article is a quick preview (and is what we showed at the LavaCon conference). I will show two examples of NetHelp responding to screen size. First, we will look at the  default layout on the desktop and phone. Second, we will examine table reflow.

Please note that this output is still in early Beta and the look and feel you see here may not be exactly the same as the final. Additionally the design is not fully polished, so please excuse any blemishes.

Default Layout for Different Screen Sizes

The simplest part of responsive design is default layout. As the screen becomes smaller, elements either collapse or stack. When the screen becomes smaller in Responsive NetHelp, the TOC collapses and the top toolbar collapse and become available via menu.

Here is what it looks like on the desktop.

Full screen view looks like traditional Online Help.

Full screen view looks like traditional Online Help.

On a phone, the menus collapse.

Default view has all menus collapsed.

Default view has all menus collapsed.

When you touch the TOC button, the TOC slides out.

When you touch the TOC button, the TOC slides out.

When you touch the menu button, the menu pops open.

When you touch the menu button, the menu pops open.

Table Reflow

Tables can be a big problem when screens get smaller. If you leave them as they are, they won’t fit on the screen and if you shrink the columns, the text will start to look very funny. Table reflow is the solution. When a screen becomes small, each row is shown individually as a vertical list. The next two screen shots demonstrate this.

Here is a table displayed in a desktop browser.

Normal looking table.

Normal looking table.

The same table reflowed for a phone.

Each records is shown individually.

Each record is shown individually.

 

See it for Yourself in Doc-To-Help 2013 v2

At the time of writing this post, we are still putting the finishing touches on Responsive NetHelp and plan to release it in December 2013.