I Need a Cheat Sheet!

Today's blog is from Brenda Roldan, Principal Technical Writer on our Elastic Charging Engine product. Brenda shares her experience working directly with customers, which has impacted her view about writing to fit the needs of the audience. I believe you'll enjoy her story.

Cheryl Lander, Oracle Communications InfoDev Senior Director

Have you ever created a cheat sheet in the process of supporting or implementing Oracle Communications products such as Oracle Communications Billing and Revenue Management? It may be that your creation can help Oracle consultants and customers. If after reading this story, you think your cheat sheet can help make Oracle Communications curriculum or product documentation more useable, let us hear from you.

Thank you,
Brenda Eiro Roldan, Principal Technical Writer

Please Point Me To a Cheat Sheet

In the early 90s I was a Social Work major who had become disillusioned with her field. After hearing I was switching careers, a friend of mine asked if I would work as a temp for an Internet Service Provider (ISP) based in Cupertino, California.  He was friends with the CEO and knew the company desperately needed front office staff.

When interviewed for the position, I learned the company was weaning off staff for supporting its ISP business, which was soon to be sold, and there were a lot of calls to return and few people to return them. I explained I had no technical skills. I had never used a fax machine or a printer. I did not own a computer nor had ever used one (since this was an ISP, I thought I should fully reveal my digital ineptitude). I was told my inexperience was not a problem. I only needed to answer the phone and fax out order forms. I was told no technical experience was required. For someone who had gotten through college writing all of her term papers on a manual typewriter, I was relieved to hear it, but I was skeptical.

Nevertheless, I was hired as employee number eight at Portal Information Network (PIN). This company would later sell the ISP part of its business and become Portal Software. Although developers were furiously coding what was later to become Oracle Communications Billing and Revenue Management (BRM), their paychecks were funded by the ISP customer base.

My initial “front office” duties were simple. I took cash and checks from walk-ins who wanted to top up their account credit (or upgrade to more than 10 megabytes of data storage). I dealt with complaint calls if our network went down (which involved assuring many disgruntled Amiga users they would soon again be able to access their news feeds). I faxed out signup forms for our PPP, SLIP, or UUCP accounts. Opening accounts back then was done manually.  Customers mailed or faxed back the forms and waited an average of two weeks to get their account connection information.

Then things became automated with the release of Web access packages; these TCP/IP software packages came with connection profiles preconfigured to connect to the service provider. The user only needed to enter a phone number, a login and password, and he was automatically connected to the ISP and assigned an account. In 1994, two such packages, Plug-N-Play Mosaic and Netmanage's Netscape Internet Chameleon, started generating A LOT of new customers for Portal’s ISP business.

In addition to generating a lot of new customers, these Web access packages were attracting a new type of customer: the non-technical Internet user. Tools with nifty graphical interfaces meant that experience was no longer required. Non-technical users could get up and running quickly and (much to the ISP’s delight) start generating usage events for which they could be billed.

I noticed immediately (the very day the packages released) that the callers were different. No longer was I hearing from users who knew what a Finger protocol meant, or who had purchased the first Commodore Amiga 1000. Now I was hearing from grandparents who had received their first computer as a gift. And, they were asking questions like “What exactly is the “World Wide Web?” and “How do I find the My Computer thing?” and “Can you help me get on the Internet?” Suddenly Manual-Typewriter Girl had become Tech Support. How did this happen?!

To make matters worse, one of the Web access packages had a glitch in its automatic account creation profile. The customer’s account was created, but their computer was only partially configured, so they could not connect to the network. There was a marked influx of tech support calls. I informed my supervisor that I did not have the skills to handle such calls, to which she replied, “Don’t worry. You can use the cheat sheets. We are strictly a connection provider. The cheat sheets contain all the information they need.”

Our “cheat sheets” consisted of the connection parameters needed to connect to the network, but contained no detailed instructions. Though adequate for experienced users, I knew these cheat sheets would not help the grandparent who was trying to set up his/her birthday gift.  I tried faxing the cheat sheets for a while, but users would call me back frustrated that they didn’t know what to do. I felt badly that our documentation was not helping them (they were so nice on the phone). I really wanted to help them get connected.

Alas, many a day I spent walking an Internet newbie through the arduous steps of finding their Control Panel and setting their Netmask Address and IP Default Gateway settings correctly (something I wasn’t really supposed to be doing, but how could I keep Aunt Martha from connecting to the Internet for the very first time?). The ironic thing was since I didn’t own a computer, and the one at work was a Sun Workstation (which did not have a Control Panel), I had to borrow time on a friend’s Dell to figure out how to walk users through the steps on a Windows machine. I remember going in on Easter Sunday (much to the CEO’s surprise) to fax fifty cheat sheets (yes, fifty!) along with my customized instructions, which gave them the details they really needed (inadvertently starting my technical writing career in the process).

I learned two things from that experience. One is that you tend to want to help people more after you have spoken to them and heard their story. Two is that when you know the skill level of your audience, you can create documentation that suits their needs. Some readers will only need a cheat sheet while others will need step-by-step instructions.

What kind of cheat sheets have you created when implementing Oracle Communications products? Did you create it because the existing product documentation or curriculum did not provide what you needed? Do you know of sites that often contain information about Oracle Communications products that you wish was in the product documentation? Your feedback could help technical writers like me make our product curriculum and documentation more useable.

If you have feedback, you can send an email to cgbu_docfeedback_us_grp@oracle.com or simply post a reply to this blog. Internal to Oracle, you can send feedback about the BRM family of products using the Documentation forum on MyForums.

Below are cheat-sheet worthy sites I have heard about:  

System Admin and Developer Community of OTN

OTN Garage (Official blog of the System Admin and Developer Community of OTN)

Solaris 11: Basic Administration

Solaris 11: Image Packaging System

Solaris 10 - Oracle Linux Command Comparo:

Rosetta Stone:


FWIW, we've written a bunch of them for Solaris 11, that are slightly different to the above links (which were articles created from our original cheat sheets). They're much shorter in terms of dialog:

Solaris 11 Basic Administration

Solaris 11 IPS

Solaris 11 SMF

Solaris 11 Install

Solaris 11 DTrace

We've had discussions with the Solaris doc team about including these types of things within the usual documentation library - I think this would be a big win for most users!

Posted by Glynn on May 19, 2013 at 06:11 PM PDT #

Post a Comment:
  • HTML Syntax: NOT allowed

This is a blog from the Oracle Communications Information Development team, led by Cheryl Lander, Sr. Director. She and members of her team from various functions (writers, curriculum developers, and architects) and product lines will share their approach to documentation and curriculum, all with the goal of getting feedback to improve their deliverables. We'd like to thank Joe Sciallo, UCS Tech Writer (former Sun) for pushing us into the social media world. The primary team driving this blog is called "Joe and the Blogettes"; other members include Brenda Roldan (BSS Tech Writer), Jodie Wilford (OSS InfoDev Director), Leif Lourie (SDP Curriculum Developer), and Scott T. Miller (Documentation Architect).


« July 2016