Skip to main content

Everything you need to learn Optimizely X in one place: See our resource pages for Web Experimentation and Personalization.


Troubleshooting: Test article


Pocket Guide

Writing for the Knowledge Base starts with deep empathy. The KB is part of our customers’ experience of Optimizely. Customers should think, “Great, I can do this. I’m going to get started!” They shouldn’t react to an article with: “This is complicated. I’ll figure this out later.” We always aim to be clear, helpful, and accessible.

Should this be an article?

  • The scenario should be relevant to most customers (not an edge case).

  • You should have permission to share examples publicly.

How should I explain this topic?

  • Who are you writing for? The person I’m writing this article for is thinking about _____________ when they start reading this piece.

  • What does this article do? I want the person reading this article to be able to _____________. How do I teach this person to do that?

  • Chunk content. Break up a long explanations into small, digestible sections.

  • Be clear. As the Economist Style Guide notes, “clarity of writing usually follows clarity of thought. So think what you want to say, then say it as simply as possible.”

  • Be concise. Set the stage for readers, but don’t use more words than you need.

  • Be concrete. Abstraction is the luxury of the expert. Be specific. Use examples (one, maybe two). Don’t write in marketing-speak; say what you mean.

  • Avoid humor or vague marketing languagewhen the customer is feeling pain in the product. Balance empathy with a direct approach to ease friction and get to the solution quickly.

  • When you’re done, read it out loud. Trim down extra words and long sentences. Aim for a natural rhythm.


More writing tips at a glance

  • Simple words; short paragraphs (2-3 sentences each).

  • Don’t expect the customer to read the article the whole way through; use links to take the reader directly to the section they need.

  • Be succinct, but human.

  • Use the direct form of the verb, most of the time: swim is better than swimming.

  • Ditch adverbs. More often than not, they aren’t necessarily as important as you think.

  • Use the Oxford comma. This list includes three items, two commas, and a period at the end.

  • Use contractions! You’ll sound human, and not like a textbook.

  • Use one space after a period, not two.

  • Don’t say to users. Refer to Optimizely customers or website visitors.  

  • Set up is a verb: set up the experiment. Setup is a noun: once you complete setup ...

  • Use experiment instead of test when referring to something you’re doing in Optimizely. Also: website, email, Visual Editor, Code Editor, Results page, Home page, JavaScript.

  • Avoid how to in article titles or section headers. Most of the KB is about how to do something.

  • Use Grammarly or another tool to check spelling and grammar.

Education Style Guide Help Scout StyleGuide Grammar Girl’s Quick and Dirty Tips (searchable)

Have a question? Contact the Education team (@education) by email or Slack.


Optimizely normally serves experiments on your site without any visual hiccups or noticeable increases in page load times. That said, you may encounter the following issues:

  • Your original page “flashes” or “flickers” (in other words, appears briefly) before loading your variation content

  • The page is loading slowly because of an Optimizely experiment

Usually, these issues are related to the snippet or variation code execution timing. This article will help you figure out which, and walk you through a solution.

Here’s when this article may not be for you:

  • You’re not seeing the variation appear at all.

  • Your variation content appears, but it is offset or appearing incorrectly. This is more likely an issue with the way the browser is rendering Optimizely’s changes. Watch our video or read our article on Editor Best Practices to learn more about how to make precise changes in the Editor.

Check for [root cause]_____________

If your experiment is running on the page and you’re bucketed into the right variation, but you still can’t see some of all of your changes, the problem may be with your code.

Paste your variation directly into the console. The variation code in your Optimizely experiment works similarly to the JavaScript console in your browser.

  1. If you run your experiment’s variation code in the console, and you see the changes correctly reflected on the page, then the issue is with timing or scoping, so move on to the next section on timing issues.

  2. If the changes don’t reflect on the page, then you’ll need to go back and review your variation code in Optimizely’s Code Editor, as well as Experiment JavaScript and Project JavaScript if necessary.

Solution 1


First, clear your cache:

Google Chrome:

  1. Type chrome://settings/clearBrowserData in the browser bar (where you normally enter a URL).

  2. From the Obliterate the following items from: menu, select your desired time range or the beginning of time to clear your entire cache/cookies.

  3. Select:

    • Browsing history

    • Download history

    • Cookies and other site and plug-in data

    • Cached images and files

  4. Click Clear browsing data, then close all of your Chrome windows and re-open Chrome.

Why does this technique work? The Editor will load the page as it would appear if you went directly to the URL in another tab; once you can repeatedly load the page into a separate tab outside of Optimizely, then Optimizely should be able to load the page within the Editor.

What's going on behind the scenes? The key here is to allow Optimizely to retrieve session-specific information from the browser. If this information is passed through cookies, using an adjacent tab or the same tab will work. If the session-specific information is passed through Session Storage, you'll need to load the Editor in the same tab that you just loaded your page in.

Check for root cause 2

Solution 2

Check for other issues

If you’ve checked your snippet and variation code, and they’re not the source of the problem, then try these other solutions. The first requires custom code from a technical resource, and the second is a trade-off between page load speed and flashing.

We recommend using these issues only as a “last resort” if the other solutions haven’t worked.

  1. Hide the Body of the page until Optimizely is finished running. For persistent flashing issues, you may want to hide the body of the page until the variation code has completed. 

  2. Load Optimizely asynchronously. For persistent page loading issues, the Optimizely snippet can be implemented asynchronously instead of synchronously. Asynchronous loading eliminates any delay in page load times but greatly increases the chances of flashing.

 Related articles

Didn’t find what you were looking for? Here are a few more resources to check out:

  • Article title

  • Article title

Still having trouble? Reach out to the Optiverse Community for additional assistance.