Friday May 17, 2013

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 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:

Friday May 03, 2013

Road Trip! InfoDev Goes to CAB

What We Learned at This Year's Customer Advisory Board (CAB) Meeting

You've already heard from Scott Miller, InfoDev Documentation Architect, in an earlier blog about the shift to task-based documentation (see Online Help and the Epic BFFL Throwdown of the 90s). Today's blog is about his experience attending this year's CAB meeting, which a few of us from the InfoDev team attended. Our goal in attending CAB was to interact with and learn more about our customers. Scott attended breakout sessions on our Oracle Communications Network Charging and Control (NCC) product and he shares his perspective below.

Cheryl Lander, Oracle Communications InfoDev Senior Director 


Last month, six members of the InfoDev team attended the Oracle Communications Customer Advisory Board (CAB) event at Oracle headquarters. We met with customers and re-united with co-workers from around the world. However, we did not attend any of the after-session parties because we wild and crazy writers tend to dance on the tables and sing Bruce Springsteen songs, so you’ll have to get the gossip from another source.

CAB is a three-day program where Oracle Communications customers meet with Oracle Communications product management, developers, and, this year, writers. The purpose of CAB is to tell customers about the future product directions, and to get information from customers about what they want in our products. As members of the InfoDev team, our purpose was to meet customers and find out how they work, and how they use the documentation and training curriculum that we create.

The first day of CAB was devoted to presentations by Oracle about future directions in communications technology, and how Oracle applications will enable customers to take advantage of that technology. Of most interest to me were:

  • WebRTC, or real-time communication on the Web. WebRTC enables browser to browser applications for voice calling, video calling, and file sharing. Using a browser for your primary communications device has some interesting implications. What, for example, is your primary communications identity? Your phone number? Your Facebook page? Your Web page? Oracle Communications applications  are already working on how service providers can take advantage of WebRTC, so stay tuned.
  • Data analytics. By using intelligent data collection, service providers can capture a lot of information about their subscribers. Using data such as where subscribers live, what they shop for, who their friends are, and so forth, service providers can identify who their most important and influential subscribers are. They can use this data to improve the effort to retain those subscribers, for example, to automatically provide bonus promotions. Service providers can also use that data to give information to advertisers about their target audiences. The data is stored in Oracle Communications Data Model (OCDM), which can be integrated with Oracle applications.

The second and third days of CAB featured break-out sessions for each product; for example, sessions on Billing and Revenue Management (BRM), and Network Charging and Control (NCC). At these sessions, customers and product managers met and talked, and planned the future of Oracle products. This year, it was also where writers had the opportunity to meet our customers, and find out how they work, which always tells us something about what we need to document. Here are some interesting things I heard:

  • When we write about Oracle Communications applications, we always like to keep in mind the customer experience, and, even though the person who uses a cell phone is not an Oracle customer, we like to keep their experience in mind too. The customer break-out session revealed multiple levels of customers; for example, in the case of one Oracle customer who I met, the person who uses the cell phone is Oracle’s customer’s customer’s customer’s customer. (Oracle’s customer is an MVNE, whose customer is an MNO, whose customer is an MVNO, whose customer is the person with a cell phone.) Wheels within wheels!
  • Everyone knows that the world of a communications service provider is a very competitive world, but our customers at CAB showed me how competitive their business is. For example, one of the service providers I met described how he makes changes to products and pricing at least two or three times a week, mostly in response to what his competitors are doing.
  • Sometimes we writers wonder: Just what exactly does a customer want in documentation? So, I asked a customer, and he said:
    • More information about operations; specifically, which logs files to look in, what to look for in them, and how often to look. Also, information about how to bring a system offline, and bring it back online. (In Oracle Communications documentation, the typical place for this information is in the system administration guide.
    • Information about what you can do with the applications. For example, can the OSM application handle changes to in-flight orders? Can you configure rollovers in BRM? Does NCC support an IVR system? (In Oracle Communications documentation, this information is in the Concepts guide.)
    • What are the new features in a release, or in a patch? Do the new features allow new types of products to be designed? Do any changes need to be made because of a new product? (In Oracle Communications documentation, this information is in Release Notes, and in the information about upgrading.)

In addition to introducing new directions in technology, and providing a way to meet our customers, CAB presented innovation awards to three customers who have implemented Oracle Communications products in advanced and interesting ways: Sasktel, Turkcell Superonline, and Cablevision Mexico. It’s always interesting to see how the applications we create at Oracle get used around the globe.

All in all, it was three fun and interesting days. Maybe next year we’ll go to the parties too. Look out.

We value your feedback. If you would like to suggest improvements or report issues on any of the product documentation, curriculum, or training produced by the Oracle Communications Information Development team, you can use any of these channels:


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).


« May 2013 »