Skip to main content

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

x
Optimizely

Technical content audit

Internal Article: This article is Optimizely eyes only.
Resources at a glance

Overview

What’s the problem? 

The Knowledge Base and Academy have no formal or programmatic connection to the Optimizely codebase and platform functionality. Documentation and screenshots in certain cases are out of date or incorrect. In at least one case, this has led to customer churn.

What’s the solution and what does it resolve?

This project intends to conduct a full technical audit of all existing Knowledge Base and Academy articles to ensure up-to-date reflection of Optimizely functionality at the time of the completion of the audit. All necessary updates will be published live to their respective articles. In addition, code samples will be verified and moved to developers.optimizely.com as deemed appropriate.

View a more comprehensive description in Harrison Krat's Q4 2015 technical audit project plan.

2016 Q3 TSE OKR

SF and AMS TSEs have individual OKRs to complete the following (go/holger):

  • Each engineer to publish one external update or new article per month

  • Each engineer to complete a technical audit for one external article per month, based on the technical content audit list

An update to an external article based on an issue surfaced from the technical audit counts for both items. Holger: "Double-dipping is allowed and encouraged!"

1. Identify an article

First, identify the KB article you'll audit.

  1. Open the Technical Content Audit spreadsheet. Articles in the list are prioritized by impact and effort.

    Effort is roughly based on article length and technical complexity. Short, simple articles have the highest priority.
    Impact is measured by pageviews in Google Analytics and the time since last technical touch. The most popular, least-reviewed articles have highest priority.

  2. Find the highlighted articles (in blue, below). Select an article from this list to audit in the next month.

  3. Enter your name under Notes or Assigned Audit Resources to claim the article. You now own the audit of this article.

2. Complete a technical audit

The following checklist covers all the components of a technical audit.

Technical audit checklist

Does every description of product functionality in the article match the actual functionality? (Coordinate with ENG if any functionality is in question.)

Yes / No

If the article includes code, will that code function as described for most (95%) of customers?

Does the article include all appropriate caveats or warnings about the code that should added to address major areas of confusion?

Yes / No

Are screenshots and UI descriptions up-to-date?

Yes / No

Are there typos, grammatical areas, or other inaccuracies?

Yes / No

Is the article clear and free of technical jargon, where possible?

Yes / No

Does the article link to a source code file for Optimizely functionality in an agent-only callout box?

Since the code is changing all the time and our KB articles are snapshots of functionality, this helps to provide a path to check actual functionality and keeps us organized with one source-of-truth.

Yes / No

Please revise the article directly if you find technical inaccuracies, vague or misleading descriptions, or unclear language. Once the the entire checklist is marked "yes," your technical audit is complete.

Here's the same checklist in Google Sheets. If you like, use it as an aid to take notes and track the progress of your audit. Make a copy for individual use.  

Here's an article that walks you through the MindTouch contributor process. And here are a few additional guidelines around KB style, especially screenshots.

When you've completed the audit, document your activity and publish your edits.

EDU review

Normally, you'll revise and publish edits directly. EDU will review changes automatically -- you don't need to create a JIRA ticket.

But sometimes, you may spot an opportunity to improve an article with a major revision. For example:

  • Restructure an article for greater clarity
  • Create new resources to help customers understand a concept or complete a task
  • Suggest a new article that covers a topic beyond the scope of the article you audited
  • ... and more

If you feel comfortable, jump in and start creating a draft. Create a ticket for EDU to review the article when you're done.

Or contact Yeesheen (@yeesheen) if you'd like to talk through the idea first or collaborate.

3. Document your audit

Finally, add the details of your audit to article's Edit summary feature. In the future, we'll know how recently an audit was performed.

  1. In the open draft, scroll to Edit summary field at the bottom of the page. 

  2. In a sentence, describe the audit. If you audited the article and made no edits, note that the audit was complete and no changes were necessary.

  3. Save and Publish.

When an Optinaut views the Revision history, they'll see your name, the date, and your Edit summary.

Prioritized content requests

You're always welcome to create or revise KB articles based on your knowledge and experience in working with customers. In the second tab of the content audit spreadsheet, you'll also find a prioritized backlog of requested net new content and revisions.


To claim a line item, enter your name into the Owner column. Do this before you start working on the article so others don't accidentally start the same article. 

Once you claim a request, you're responsible for documenting the article's progress in the spreadsheet.