Ensure Your Audience Understands: Clarifying a Technical Message

From Kelly Manjula Koza’s archives: I wrote this in 2014 to demonstrate how a tech company could better communicate an important update and action needed to their clients.

The first set of items is my improved version: A letter targets the person who would receive the initial communication; the instructions are illustrated and written for the person who would be doing the work; and the FAQ’s are both more detailed and simplified. The updated communication addresses different roles, different needs, and is clearer for recipients.

The second set of materials below (in grey text) shows the original letter and technical instructions a web hosting company sent to clients. The message is confusing, especially because the person who would likely receive the letter would not be the same person actually doing the work and therefore following the instructions.

Names and links have been omitted for privacy, and the formatting is not exact here.


Revised Letter, General Overview, Instructions, and FAQs

Letter

Dear Website Owner, 

We’d like to ask you (or your web developer) to run a quick test to make certain your website continues to look and function the way it’s designed. 

We’re making an upgrade to our system, and the upgrade may affect some websites, particularly if they were last updated or built before January 2011. 

The test will indicate if the upgrade would affect your website. 

If you run the test and find the upgrade would affect your website, you can easily reject the upgrade by changing one setting on the Webhost control panel (CPanel). 

Instructions, more information, and frequently asked questions (FAQs) are below. 

If you are not the web developer who will conduct the brief test, or apply any necessary changes, please forward this email to the appropriate person who handles these tasks for you!

If you have questions, please check out the FAQs and support links and phone numbers below.

Thanks, 

Webhost Support Team

General Overview

Webhost’s default servers will be upgraded to a new version of PHP (5.4) on May 8, 2014. We’ll attempt to determine if your website and any add-on domains are compatible with the upgrade by running an automated check. However, we’d like you to test compatibility yourself, before the upgrade, because you know how your website is designed to look and function, and may notice issues our automated program does not.

If you experience issues when you run the test, you have the option of choosing not to accept the upgrade. 

Instructions Overview

Detailed instructions follow this overview. 

To give you a brief overview of the steps to test your website for compatibility, you will:

  • Log into your Control Panel (CPanel) for your home directory
  • Set the PHP handler to the new version of PHP
  • Open your website(s) in a browser
  • Access each page (in each) of your website(s) to check for any visible or functional changes or errors
  • If you do NOT encounter issues on your website(s), your websites are compatible with the upgrade, and no further action is necessary
  • If you DO encounter issues on your website(s), you can decline the PHP upgrade by setting the PHP handler to continue using the current PHP version 5.2

Instructions: Testing Compatibility

  1. Click this link, or copy and paste into your browser, to open the Control Panel: SAMPLE LINK NONFUNCTIONAL
  2. Scroll down to the Advanced section.
  3. Click PHP Configuration to open the PHP Configuration window. 
pastedGraphic.png
  1. Click the drop-down arrow.
  2. Select PHP 5.4.
pastedGraphic_1.png
  1. Verify you see the confirmation message: “The “.php” file extension will be processed by PHP 5.4 for this account” in the new window.
  2. Click Back on the browser bar.
  3. Verify you see “The “.php” file extension will be processed by PHP 5.4” in the PHP Configuration window.
pastedGraphic_2.png
  1. Open your website(s) in a browser.
  2. Access and view each page in each of your websites.
  3. Check for any visible or functional changes or errors.

If you do NOT encounter issues on your website

  1. You do not need to do anything further. If you still have the CPanel open, click the Logout icon in the upper right corner of the CPanel window to log out of the CPanel. You’re done!
pastedGraphic_3.png

If you DO encounter issues on your website

  1. Return to the CPanel PHP Configuration Page (if the CPanel is no longer open, follow steps 1 through 3 under Instructions: Testing Compatibility).
  2. Click the drop-down arrow.
  3. Select PHP 5.2 to set your website and add-on domains to use the current version of the PHP handler. Your site(s) will not be affected by the upgrade
pastedGraphic_4.png

Our upgrade process honors the settings you choose here, so setting your PHP handler to 5.2 essentially declines the upgrade to PHP 5.4. 

Please note: If you want to decline the upgrade and continue using PHP 5.2, DO NOT select “No custom PHP Handler (Sys Default)”. While the System Default (Sys Default) is currently PHP 5.2, once the upgrade is performed, the Sys Default will be PHP 5.4.

  1. If you still have the CPanel open, click the Logout icon in the upper right corner of the CPanel window to log out of the CPanel. You’re done!
pastedGraphic_3.png

FAQs

Why are you making this change?

We want to bring you the best and most up-to-date software and services available.

Our servers currently use PHP 5.2, which is an deprecated version of PHP that is longer supported. Version 5.2 and does not offer the security and performance improvements found in Version 5.4.

How can I make sure my site(s) will work following the upgrade?

Simple answer: Follow the instructions given above. You can also find the instructions online at SAMPLE LINK NONFUNCTIONAL.

Details: If you follow the instructions above, and find your site/scripts do not work with PHP 5.4, as well as declining the upgrade, you could consider rebuilding your site/scripts using newer code/applications/technology.

Will my site(s) experience any down time?

Simple answer: If you have followed the instructions above, your site should not experience any issues or “downtime”.

Details: The switch between PHP versions is simply a configuration change in your .htaccess file(s). There not maintenance performed on the server that would cause any service outages. 

However, websites and scripts incompatible with PHP 5.4 will not load properly once the upgrade is performed, and may experience issues, including issues that prohibit visitors from accessing or using your website properly.

While we perform automatic compatibility checks for each account and attempt to set the PHP handler version automatically for each site, it’s imperative you perform the compatibility test before the upgrade on May 8, 2014 to ensure that your site/scripts work with the upgrade — or that you decline the upgrade. 

Who can help me update my site to use a newer version of PHP?

Simple answer: Your web developer or technical team members.

Details: If you have an older website that has not been updated for some time, you may consider rebuilding the website with newer versions of code, applications, and/or technology. Such an upgrade can improve performance and security as well as help you update the look and functionality of your site for users.

While we can help you change the version of PHP your website uses on our servers, we cannot rebuilt your site to use newer versions of PHP. You must contact the web developer and/or technical team members who built the website.

Where can I find these instructions online?

Go to SAMPLE LINK NONFUNCTIONAL.

Support Contacts

  • Chat: Click here
  • Email: Support@webhost.com
  • Phone: 1.888.888.8888

Original Letter Before Revision

Dear Valued Customer,

We’re writing to inform you of an important change in your server’s default configuration that may affect your websites.

The default version of PHP employed by our servers will be updated to PHP 5.4 on 5/8/2014. We will be attempting to automatically detect the compatibility of YourSite.com and any other add-on domains you have, but we want to ask you to please log into your cPanel and test all of your sites using PHP 5.4 by following the directions given in this article: SAMPLE LINK NONFUNCTIONAL.

FAQ‘s

1) Why are you making this change?

The default version of PHP that our servers are currently utilizing; PHP 5.2 ; has been deprecated for some time. As such, we would like to see your sites enjoying the security and performance benefits of the newer versions of PHP which we already have available on your server.

2) How can I make sure my sites will work?

While we are taking every possible step to try and automatically assign the right version to all of your scripts, we do want to ask you to please login into your cPanel and test all of your sites using PHP 5.4 yourself.

Here’s a more detailed explanation on how to test this using our plugin available via cPanel.

The default behavior of your account is for PHP settings to be inherited by sub-directories. That means that you can easily test all of your site’s compatibility with PHP 5.4, by setting the PHP handler for your home directory for your account to PHP 5.4. Then simply test your websites by opening them in your browser.

To test this using our plugin please do the following:

* Login to your cPanel at https://host.1000.Webhost.com/cpanel

* Click on the “PHP Configuration” icon, which can be found under the “Advanced” group of icons in cPanel.

* From the drop-down of Available PHP handlers, please select “PHP 5.4” without changing the target directory from the current setting.It should be displaying / (Current Folder). Click on “Update”

* You should see a confirmation message that reads: The “.php” file extension will be processed by PHP 54 for this account. Clicking on “Back” you should now notice the dropdown listing PHP 5.4 as the active Handler

* At this point you will want to test your sites by opening them in your browser. If you do not notice any issues or visible errors, this means your sites are compatible with PHP 5.4 and you do not need to perform any further actions to ensure they continue to work once the PHP upgrade is performed. You will simply want to leave the Handler that was just set as the active one without any other changes.

* If on the other hand, you do notice issues during your test with your sites and the PHP 5.4 Handler that was enabled, you can then simply toggle the active Handler via our plugin and set it to use “PHP 5.2”. This should set your account to specifically use the the current default version of PHP in our servers and ensure they continue to use this version once the PHP upgrade process is performed. Our upgrade process is set to honor the current Handler settings you set via this plugin to ensure your scripts continue to work once the upgrade is completed.

Please note: Selecting “No custom Handler (Sys Default)”, will NOT ensure your account stays using PHP 5.2 once the PHP upgrade iscomplete. While PHP 5.2 is currently the system default version, once the upgrade is complete, the default version will be PHP 5.4. If your applications require PHP 5.2 you will want to make sure to specifically select the “PHP 5.2” option.

3) Will my site’s experience any down time?

The switch between PHP versions is simply a configuration change in your .htaccess file(s) as such, there is no maintenance which must be performed on the server itself that would cause any service outages. Applications that are not compatible with PHP 5.4 will fail to load properly once the change is performed. While we will make every effort to automatically perform compatibility checks for each accounts and set the appropriate Handler, it’s imperative for you to please do the compatibility tests from your end as well using the steps listed above, before 5/8/2014 .

4) Who can help me update my site/script to use a newer version of PHP?

While we can assist you with changing the version of PHP your script utilizes, we will not be able to recode your site to be compatible with newer versions of PHP. You should contact the script’s author/developer to inquire as to whether or not they currently have or plan to re-design their code to utilize later versions of PHP.

Best Regards,

Firstname Lastname