Inline Manual Blog

"Lets sort out the murky world of documentation!"

Yarn - first impressions and future prediction

8 months ago

Facebook released Yarn - a package manager that is supposed to replace NPM. What do I think? TL;DR: Yarn is great, but it will be irrelevant soon. NPM too.

Yarn logo

What is Yarn?

Yarn does the same thing as NPM. It's a dependency manager. It just has few extra features. The important ones are:

  • It makes sure that everybody installs the same versions of packages in the same form. Just like Shrinkwrap, but native. If you already use Shrinkwrap, or you're afraid of another LeftPad scandal, Yarn is an easy solution.
  • It supports offline mode. If you already installed some version of a package, you don't have to download it again. You can add it to a new project even if you don't have an internet connection. Which is great for digital nomads sitting in coffee shops with poor connections.
  • It's fast. Two reasons: First, there's no problem with slow progress bar redraws (which was already fixed in NPM). But more importantly, it downloads packages in parallel (NPM downloads them in waterfall style). If you have large project with lots of dependencies, the speed difference is significant.
  • One tiny feature nobody talks about yet: Yarn takes care of dependencies from both NPM and Bower. So if you still use Bower, this could simplify your workflow.

Should I use Yarn?


If you deal with any of the points above, you can start using Yarn right now. So far it is fully compatible with NPM. Just install Yarn, type yarn and you're done.

However, if you have lots of small packages and you don't have any solid reason to migrate, then it's not worth it. NPM isn't going anyway and it will stay with us for very long time.

The only problem with Yarn I encountered so far are dependencies on packages linked directly from private Git repositories. But that should be easy to hack.

A little bit of history

Before I reveal my forecast of Yarn's future, let's go back in time a little bit.

Do you remember Grunt? The build system used by everybody. But then some developers started to grumble, that it's slow and needs lots of configuration.

And so Gulp was born. A shiny new build system. Very fast, compared to badly configured Grunt. And it made sure to be in your face about that. In the console, every line contained information about how many milliseconds this task took. It was a perfect marketing strategy. Everybody was ranting about how fast Grunt is, while the true innovation was the use of streaming.

Everybody predicted that Grunt will die and everybody will use Gulp, forever and ever. But what happened? Since developers started to notice the build process problems, they migrated directly to native NPM scripts.

Grunt and Gulp still exist. But nobody cares about build tools anymore. The problem is already solved. Everybody cares about the new stuff - transpilation and package management.

Back to the future

I think the history will repeat itself.

Yarn in console

Just look at how Yarn brags about the speed. It even brags about the speed during tasks that depend on user interaction! That's the same marketing trick used by Gulp. And again, everybody is raving about the speed, while the key feature is version locking (Shrinkwrap).

Now, since this problem will attract the attention of developers, I think they will again come up with a completely new and different solution, making the package management problem irrelevant. I personally think it will be something, that:

  • analyses source code, finds all imports and requires
  • does smart lookup for linked packages
  • is based on package content finds relevant loaders and transpiles it
  • shakes the tree and eliminates dead code
  • runs the result through tests
  • saves valid output

This way we will get rid not only of package managers, but also Webpack, Babel, Rollup and who knows what else. Well, no. We won't get rid of them. But we will hide them into the background. So if we don't want to, we won't have to deal with them.

The nice side-effect will be that we will also get rid of these quasi-funny articles.

I can't wait.

What about you?

Did you already try Yarn? Will you use it in your projects? What do you think about Yarn and its future?

About the author

Riki Fridrich, @fczbkk, lead frontend developer at Inline Manual.

PS: You can also read original Czech version of this article here.

We're hiring!

We're looking for JavaScript developers! Come join our team.

Take control - Part 2 - How much control will I have?

8 months ago

If you choose a DIY solution, there can be an increasing amount of friction building up between customer-facing teams and product-focused teams when implementing tours, tips and tutorials. In Part 1, we looked at this issue to try and understand the issue from both perspectives.

On the one hand, marketing and support teams want to respond to opportunities and user needs quickly. On the other, engineering teams are concerned about switching to a third-party service because of the lack of QA and testing, and poor design capabilities.

If you’re stuck in this situation, we’ve listed some of the issues below, and how you can address your concerns with Inline Manual. We do think Inline Manual will be much better than a DIY solution if you’re running into these problems. However, with every change you have to evaluate the gains and losses by comparing it to your current solution.

Let’s look at the kind of control you will be able to have with Inline Manual.

What about installation and updating?

  • The player: You will need one line of code installed in your application to have the player right in your app. If you want to have advanced segmentation and analytics with People tracking, you will need to have a few more lines of code installed. They player works on any browser.
  • The authoring tool: You will need Chrome just for authoring. If you have control over installing extensions in your browser, you can install the Inline Manual Authoring tool into Chrome.

The good thing is, once you have the player installed on your app, and the authoring tool installed in your browser you’re good to go!

You do not need further support from your engineering teams to keep Inline Manual updated.

Will I be able to control configuration?

You will have full control over your account.

  • Add new tours, tooltips, launchers and knowledgebase articles
  • Control who sees content, such as welcome screens targeted to specific users

You can also add collaborators with role-based access, as owners, writers and readers to give tiered control over each site.

We need WYSIWYG content creation and interactive design

With the authoring tool you can add and edit content, and control how it appears.

  • Include a video in a tour,
  • Edit the HTML directly,
  • Dim a screen and highlight single or multiple elements,
  • Lock down the UI so they can’t click actions until users are prompted,
  • Position launchers on the page and within contexts or sections of an application.

These are all of the kinds of things you will easily do in the authoring tool.

We want Total Design Control

Marketing and Engineering teams especially will be glad to hear you have total design control to make the tours look like they are seamlessly part of your product and not just a third-party add-on.

  • Are you not experienced with HTML and CSS?
  • Inline Manual can inherit the CSS from your website and instantly just match the look and feel of your site.
  • You can click to change colours using our design tools.
  • Are you experienced with HTML and CSS?
  • You can edit each step’s HTML directly.
  • You can also edit the CSS of your tours.

We also offer help from our customer success team to integrating Inline Manual and helping you achieve a seamless experience to match your brand.

What insights are available with Analytics and People tracking?

Analytics will work right out of the box. Access depends on your subscription level.

  • Which tours are really helping people?
  • Where are users getting lost or dropping off?

Having access to Inline Manual’s analytics will allow you to compare the experience across your application and see how users are benefiting from the content you create. For example, our customers often see higher completion rates for tasks.

People tracking on the otherhand, is one thing your developers would configure. (A few lines of code, similar to installation!) People tracking will let you see user-by-user who is playing and completing your tours. Having that information is helpful because you will be able to make sure auto-launchers for specific groups of users. It also helps with segmenting so you can control who sees what.

We want reliable QA and testing

Marketing and Engineering both want a clear quality assurance process.

With Inline Manual you can create a QA and a production site, each with their URLs and unique API keys. When you create a new walkthrough, you can assign it to the QA site and test it there. Once you’re happy you can assign it to the production site. You don’t have to do kludgy things like duplicate it, or recreate it.

This is all done within the administrator dashboard, and again you don’t have to lean on your development team to deploy.

This leads us to talking about version control and releases.

Can the marketing team handle version control and releases?

You can create releases as you make improvements and iterations to your content, all from within the admin dashboard. And again, you do not have to ask for help from your developer team.

This is super helpful when you are preparing to launch a tour for a new campaign. Once you understand how to create releases, you will be able to manually specific the new version of your content and control when your campaign launches.

The great thing is, this puts marketing teams in control of their timeline, and not tied to the development schedule.

If you’re wondering what kind of control you can have - sign up to our next webinar to see how to Get Started with Inline Manual.

Take control - Part 1 - When DIY is not A-OK

8 months ago

Though some of our customers are new to creating guided tours, many do have experience with building walkthroughs developed and controlled by their product development and engineering teams. At some point, they outgrow this process and come to Inline Manual.

Naturally, one of the most common questions we hear when they join our webinars and demos early in their search is “How much control will I have?” Or as one client put it more plainly: “Can I get this out of the hands of engineering?” Ouch.

DIY is not A-OK

At the start, development or engineering teams implement open source libraries to build tutorials, tooltips and tours right into their applications. This works really well for a little while. Marketing teams see people are completing their onboarding, the support teams see less tickets. Everyone is happy! This works for a little while, until suddenly it just doesn’t.

Especially when the teams are small, it means communication is easy, and any required changes can be made quickly. As a small company grows, or of course in larger companies, the people who see the need to build those tours are based in the marketing or support teams.

This means requests for changes to tutorials get filed alongside bug reports and feature requests. In terms of priority, this means they may have to wait days or weeks to see their changes made. Each request must be carefully communicated, because any further change means yet more delays.

This means they have a number of problems.

What are some problems a DIY approach creates?

  • Authoring and creating content is slow.
    • Requests for changes can take a long time to fulfill. Even with simple text changes, each new alteration is a new “work request” or backlog issue, subject to the prioritization of product development.
  • It’s not possible to change content on the fly.
    • Depending on the workflow, it can sometimes mean a marketing team member must hand over a document which carefully specifies the text, directions, and click actions to design a walkthrough. They have to include marked-up screenshots to even show where to place the launchers or tooltips. Then this has to coded and developed with skills only a developer has, and precious developer time is tightly time-boxed.
  • Not on the same schedule
    • Because of the reasons described above, though the marketing team might need a tour to be updated now, they still have to wait until the planned release to see their changes live.
  • No Analytics. Lack of visibility into results.
    • The teams who need to track results have little insight into which content is performing best, and where people are getting lost in drop- off funnels. They may be using site analytics, but it’s difficult to identify where the content is helping or not.
  • It’s time-consuming to develop and test.
    • Selecting the right elements, testing, and managing the tours - it all gets complex when you’re taking a code-only DIY approach to managing the content.

We hear about these issues from our new customers. These are not terrible tales of woe. These are normal, practical problems and friction they deal with day-to-day. And, it was all probably manageable until it became clearly too costly and time consuming. Small frustrations like these seems to build up until it’s just too much.

At some point, they come to the conclusion that the time spent in communication, coordination and development of product tours could be better spent by moving control over to the marketing and support teams who are closely monitoring user engagement and needs.

The problem is, our potential customers must evaluate all of the onboarding solutions out there, find a good one and then finally, convince their engineering teams it’s time to let go.

What is engineering concerned about?

Considering the amount of friction a DIY solution can cause, you have to wonder then, why would engineering teams be so unwilling to let go of this? When their response is delayed, it can make marketing and support teams feel like communicating with customers is must be considered low-priority by engineering teams.However it’s more likely the opposite, that the engineering teams do hold this as very high-priority, and they want it to be as high- quality as their app, QA tested, and seamlessly branded.

In fact, engineering might be afraid that using a third-party solution will mean it would be inferior to what they can craft bespoke for their application. Let’s consider their concerns.

  • What about the lack of design control?
    • They want to be able to control of the CSS entirely. They want to inherit or reuse the existing CSS from their application so updates are easier to manage. They don’t want a third party solution confusing their brand experience.
  • What about the display, positioning, placement?
    • They’re concerned about being unable to control where tips appear, by either choosing selectors, or manually editing selectors, and placing where they appear.
  • Do we want to do maintain yet another third party service?
    • They might worry about having to reconfigure every time a third party service updates. Or having to engage a third party service who charges for yet more professional services just to make the basic features work as expected.
  • What about the lack of QA and testing? Don’t touch the live site!
    • They’re worried about letting support and marketing teams edit interactive elements which will be edited LIVE on a LIVE site. That is crazy talk. They prefer clear points for QA, testing and deployment. They don’t want to deal with kludgy workarounds of copying or re-creating tours.

Finally, and this might sound harsh, but some extent Engineering teams feel guilty about adding tutorials to apps. It’s a delicate subject to broach. Admitting your UI needs a tour is like saying there’s an inferior user experience that needs an interpreter. User experience designers may, as Kathy Sierra said, think a product should be so good it doesn’t need a manual.

Engineering teams therefore might feel the issues could be fixed with a better design. Maybe they have to tweak the UI or add another feature? And this explains why product-specific issues can take precedence when there are requests for updating a product tour.

Of course engineering will continue the conversation with users to find tweaks and improvements to the interface. What engineering teams don’t know yet is that by having contextual help, tutorials and auto-launching tours they can provide a more empathic user interface which gives support to different customer groups even better than they can in their UI.

For example, new users might leap delightfully into a new UI or feature, and yet existing users might need more hand-holding to manage the change to un- stick their habits. There are also certain kinds of users to playfully discover in a UI, and other users who really want assurance the entire way.

Perhaps there isn’t even a clear way to tweak the UI to help all users. But a guided tour can, and perhaps even smarter by providing specific user groups the right messages. When the engineering and product teams give control of this layer to their customer-facing colleagues, they can have a more emotionally responsive and helpful UI. And, it can save hundreds of support requests from existing users asking “who moved things around here?”

In Part 2, we’ll answer your questions about how much control you’ll have when you’re using Inline Manual.

Continuous user onboarding - Part 3 - In-app trouble spots for redesigns

9 months ago

In Continuous user onboarding, we explored how to take what we do with new user onboarding, and apply those same techniques to keep users engaged and informed.

Our customers are looking at ways of improving their customer retention. They want to make it easier to tell their users about the benefits of their new features. To do that, they auto-launch greetings and offer their users step-by-step tours, as we showed in Part 2 tutorial on adding personalized greetings.

In this tutorial, we’ll see how to place tooltips and step launchers in potential trouble spots in your application.

Why do you need tooltips or launchers anyway?

It’s ideal to design “a perfect user experience” which tests well with new users and is clearly going to be a major improvement to your UI. However, it might not be perfect for everyone.

When you roll out a new version of your application, suddenly users can get lost in this new workflow. It’s not working as they expected. You find out when they start sending support tickets. And those are only the ones who took the time to contact you.

Our customer, Bannersnack, recently relaunched a new UI design. Their development team had researched user needs to improve the UI to help their users create effective ad banners even without graphic design experience. Of course the loyal users did love the new UI because it addressed each one of their concerns in the new design. Yet they needed additional help, and it’s no wonder. What had become automatic actions were now interrupted, meanwhile, new users would have no built-in expectations, and they took to it easily. “Most support requests about the redesign came from existing users,” said Andrew Tiburca, Marketing at Bannersnack. So they decided they wanted to have a tool to explain new features to their users. That is where Inline Manual comes in.

Here are some ideas of how you can add tutorial in potential troublespots in your new redesign.

  • At a point where the UI has changed
  • Around the location of a new feature
  • Draw attention to a new section or tab on your UI

What are tooltips and step launchers?

Launchers sit patiently in your app, inviting curious users to click them.

A tooltip provides additional information and help for users without cluttering up your UI with explanatory text. A step launcher on the other hand can guide users into a step-by-step tour or tutorial to help them get their work done. You can launch a tour from the start, or add a launcher to specific step so the users can skip ahead.

Both tooltips and step launchers contain two parts:

  • There is a launcher, for example a small question mark is commonly used.
  • There is content.
    • Create a Tooltip if you have a pop-over message you want to share.
    • Create a Walkthrough and add the launcher to a step.
Next we’ll show you how to create a tooltip.

How to add a tooltip

In this example, we will add a tooltip to highlight changes to this form. We have content editors adding products to this site, and we’ve added a new feature for out of stock products.

The tooltip launcher appears in as (a question mark on the left). The tooltip content appears as a popover to the right.

Add the tooltip

Open the authoring tool and add a new Tooltip.

Configure the tooltip

In the Tooltip panel you can adjust the position of the launcher and the step popover.

  • Assign Launcher, I assigned the launcher to appear to the right of the sidebar title.
  • Assign Step, I assigned the step to point to the slider which is my new feature.

Set this launcher to always be visible. Next we can set it so it’s only visible on this particular page.

Configure the launcher

In the Launcher panel, set the context path to make sure the launcher only appears on pages at this path: /node/add/* This is a good thing to do with every tooltip or launcher to add. This optimizes the performance.

In this case we had to slightly adjust the positioning, which is set under Offset. If we wanted to, we could change the content here from a question mark (?) to an exclamation mark (!) for example.

Now you can save your Tooltip and you’re ready to go.

Other ways to use tooltips:

Imagine a case where you have many changes in the UI. You can create multiple tips to highlight what is different in the UI.

  • In this case, users can click one topic launcher to activate the tooltips.
  • And then all the tooltips are active and visible.
  • When they dismiss one tooltip, it deactivates all of them.

How to do this

Add several tooltips which are only visible when Active.

If you’re already using tooltips, this is a handy way to group them together and make them easier to manage as well.

Next, add a Launcher

Set this Topic Launcher to always be visible, and make sure to configure the context path, so it appears on the right page and subpages.

Now when users click the launcher, it will activate the rest of the tooltips on the page.

Launchers are really helpful. You can add them to any step, and launch users right into a step-by-step walkthrough. See how to add a Step Launcher for more information.

Responding to a worst-case scenario: Fast

It’s natural to be optimistic, and hope everything is going to go smoothly. Sometimes with redesign launches new bugs are reported, which it seems can only be discovered after you’ve gone live. Murphy’s Law seems to be in effect!

When things don’t go smoothly, many companies put on more support staff, extend their hours and wait for the improvements which can take weeks or months.

The great thing is, you can respond quickly by creating a launcher in a trouble spot in your application. The marketing and support teams can be fully in charge of building tooltips and launchers. They don’t have to wait until a new version of the application is deployed. Inline Manual runs completely independently.

The development team can focus on the important bug fixes and improvements, and meanwhile the users can have a better experience.

If you’re wondering how to get started with Inline Manual, please sign up to our webinar Thursday, 22nd September

Read the other posts in this series on customer retention.

Triggers now with branching - react to user activity with more flexibility

9 months ago

The trigger is the most important component that advances a user’s progress through your walkthrough. With triggers, you can react to user activity and bring users to the next step in reaching their goals.

How do triggers work?

A trigger has three parts

  • An event: What does the user do? Click something, hover over something
  • A destination: Where should we go? Jump to a step in the walkthrough.
  • An assigned element: What are users interacting with in your UI? By default this is the step element, but each trigger can be assigned to its own element.

For example, you might have a step where users click the assigned element, and the walkthrough advances to the next step. Or you may have a step where users have several potential options to choose from, and each should go to a specific step in your walkthrough. These are examples of when you’d use Triggers. Without triggers, you have no way to get users to the next step in a walkthrough.

Check out the help page for an in-depth look.

Major trigger update!

We’ve just updated Triggers to give you more control over the types of events you can respond to and also where users can go.

  • More mouse events. With the addition of Mouse enter and Mouse leave, you can respond better when users interact with dropdown menus or other elements which appear on mouse hover actions.
  • Go anywhere! Before, the only available action was to go to the next step. Now you can go to the Next step, Previous, any step available in your tour, or even deactivate the topic.
  • Easier to identify multiple triggers. Each new trigger is color coded to make them easier to identify. Click the eye button and the element you have selected which be outlined in that signature color. colour coded
  • Sensible default options, with Expert control available. When you assign an element, our Authoring Tool will choose the best and most specific element. However you might want to manually edit this selection, and you can now by clicking “Expert” mode.

These changes make it easier to create triggers to respond to user actions in your UI.

Easier to manage Dropdown menu actions

Say for example you have a dropdown menu, and by Step 2, you’re directing users to select from a sub-menu of options. What happens if they move their mouse out entirely and the menu closes?

In this case, two triggers are better than one. You can start with one trigger which responds to a click and advances your user to the next step. By adding a second trigger, you can have a fall back to go to Step 1 again.

To find out more, check out this tutorial on managing drop down menus with triggers.

Indicate your final step

Using Analytics, our customers like to track whether their users complete a tour. Usually, this is the final or end step on the list by default. Now with the availability of multiple triggers from a step, you can create a kind of branching in your tours. For this reason you might have multiple valid end points you want to track.

For example, on a specific step, you might offer the user to choose from two possible options. From there, they might have one more step to complete, but each “end step” will be different depending on which option they chose. If a user reaches either of those end steps you want to know they completed their task.

Now you can specify which steps you would like to track as End steps. Under the Misc panel for a step, enable End step. And you’re all set!

Want to learn more?

We’ll take a closer look at triggers in our webinar on Thursday, 8 September. Sign up to find out how to create engaging user onboarding and tutorials.

Sign up for webinar

Upcoming free webinar

Inline Manual Product Demo

Thursday, June 1, 2017
4:00 PM - 5:00 PM GMT (BST) - London
9:00 AM - 10:00 AM PST

Sign up for webinar

Notify me about tips and new features