Friday Mar 01, 2013

Online Help and the Epic BFFL Throwdown of the 90s

Today's blog is written by our very talented Documentation Architect, Scott T. Miller. I've watched Scott perform his writing and architecting magic for nearly 14 years. From this blog you'll get a good sense of his story telling ways that make learning from him so much fun. Enjoy!

Cheers,
Cheryl Lander, Oracle Communications InfoDev Senior Director

In the technical writing field, writing online help in the early 1990s was totally hip. We online help writers were ten pounds of hip in a five-pound bag. Lady Gaga had nothing on us, although in fairness she was only five years old at the time.

So when I ran into my afore-mentioned BFFL, whom I hadn’t seen for a while, we exchanged our latest news. He was in the heavily-airquoted “import” business, and I told him that I was writing online help, and I was, therefore, extremely hip.

He was not impressed.

“Online help?” he said, “You mean that stuff that comes up when you click the Help button?”

“Yeah,” I said, “How hip is that!”

Common decency prevents me from relating his comments as dictated, but the upshot was that he did not find online help to be helpful, and also if he had a will, he would have written me out of it. And here we had gone through grade school and high school together! And later we went to Guatemala together where we kinda sorta accidentally robbed a bank together!

But that’s another story. The point is, we had a history, and he was going to unfriend me, even before “unfriend” was a word, all because of a mere online documentation delivery mechanism. I mollified him by reminding him that I had rescued him from a burning tire factory, and he calmed down enough to say this about online help:

“Just tell me how to do what I want to do.”

As it turned out, I was not the only technical writer to hear such sentiments. What had happened? How could something so hip be so, as it turned out, tragically unhip?

What had happened was that the world had changed more than somewhat since the days that technical writing was about such straight-forward topics as “Lubricating Your Water Wheel” and “Proper Usage of the Butter Churn.” How to use a butter churn is not that difficult to document:

Hardware is one thing, but along came software, and writing instructions for how to use software can be much more difficult:

So, sometime around the early 1990s, the technical writing profession engaged in some pondering and reflection. (We were tired of getting written out of wills.) Previously, good technical writing was “accurate and complete,” and that was enough. Water wheels got accurately lubricated, butter got completely churned. We found, however, that documentation could be accurate and complete and still not very good.

We took another look at the online help that we were writing. It looked like this:

It was accurate and complete, but all it did was describe the software. Instead of describing the software, we starting writing about how to use it. Online help began to look like this:

This works a lot better. It lists the tasks that users want to do, and tells how to do them. Good technical writing is still accurate and complete, but it also helps users accomplish their goals. We call this task-based documentation.

After we started writing task-based documentation, users seemed to like our writing a lot more. We began to pay a lot more attention to our users, including visiting customer sites to find out how they work, and what tasks they need to accomplish.

Which brings us to the point of this story. To write documentation that meets customer goals, we need to know our customers. If you have anything to tell us about how you work, or about our documentation, which would help us write better documentation, let us know.

In case you’re wondering about what I and my BFFL have been up to in the last 20 years since the events described here occurred, my BFFL is now a lawyer (nobody saw that coming) and I��m still writing technical documentation. It beats robbing banks.

We value your feedback! You can either respond to this blog or contact Oracle Communications Information Development using our email alias: cgbu_docfeedback_us_grp@oracle.com.

 

Wednesday Feb 20, 2013

Brokering in Three Dimensions: Oracle Communications Service Broker Successors

Now that the successors of Oracle Communications Service Broker have been released, we’d like to provide some information about the documentation for these products. This information was provided by Osnat Rabi, Service Delivery Platform (SDP) InfoDev Team Lead. Osnat has been working in the Telecommunications industry for over 17 years at various companies as a software engineer, project manager, system engineer, and product manager. Her passion for writing and organization have kept her close to product documentation throughout her career and she is now leading the documentation and curriculum effort for the SDP team.

The successors to Oracle Communications Service Broker are:

  • Oracle Communications Converged Application Server, Service Controller 6.1
  • Oracle Communications Online Mediation Controller 6.1
  • Oracle Communications Policy Controller 6.1

In the previous release, these three products belonged to the same product line, Oracle Communications Service Broker. In release 6.1, each of the Oracle Communications Service Broker products is marketed as a separate product and has separate documentation. Some of the content is generic across the three products (for example, the Concepts and Installation Guide) and some of the content is product-specific.

In addition to documenting all of the new features for this release, we made the following improvements (the links below, from Oracle Technology Network, where the doc is common across the three products, are for the Oracle Communications Converged Application Server, Service Controller version):

  • Oracle Communications Converged Application Server, Service Controller documentation now has an Implementation Guide that describes the various product use cases and how to set them up.
  • All of the information about service orchestration is now consolidated in one book, the Orchestration User's Guide. In that book you can read about the concepts of orchestration, how to configure the Orchestration Engine, and how to use the Orchestration Studio to create service orchestration logic. 
  • We created three new Protocol Implementation Conformance Statement (PICS) documents. You can consult the PICS documents to understand the standard protocols that are supported by the products and determine what standard requirements are met by the product's protocol implementation. There is one for each product: 
  • The Processing Domain Configuration Guide and Signaling Domain Configuration Guide have been renamed to Modules Configuration Guide and Signaling Server Units Configuration Guide. They cover configuration of Interworking Modules (IMs) and Signaling Server Units (SSUs).
  • The five Service Broker Java API References are now consolidated into the Configuration and Runtime MBean Java API Reference, which covers all of the configuration MBeans and runtime MBeans of the three products.
  • The configuration documentation describes how to configure modules and SSUs using the Administration Console, and no longer provide a reference of the Configuration MBeans. The Configuration MBeans are described in the Configuration and Runtime MBean Java API Reference.

The documentation for these three products are available for download on Oracle Software Delivery Cloud and on the Oracle Technology Network. Documentation is available in PDF and HTML format, as well as ePub and Mobi formats for mobile devices.

We value your feedback! You can either respond to this blog or contact Oracle Communications Information Development using our email alias: cgbu_docfeedback_us_grp@oracle.com.

Friday Feb 15, 2013

Operational Support Systems (OSS) Documentation ROCKS: More Content, More Searches, More Downloads

I’d like to introduce Jodie Wilford, Oracle Communications OSS InfoDev Director. She’s responsible for managing all of the documentation and curriculum for the Oracle Communications Operational Support Systems (OSS) products. As part of the MetaSolv Software, Inc. acquisition, she joined Oracle in February 2007. She has extensive experience in documentation, curriculum development, and training delivery.

Jodie’s team did a lot of great work in this release that she outlines in this post. Thank you Jodie and OSS team for all your great work.

Cheers,
Cheryl Lander, Oracle Communications InfoDev Senior Director


Thank you, Cheryl. I would like to tell you about the latest release of OSS suite of applications that Oracle’s Communications released in January 2013. This is the second release in nine months which is a consistent, coordinated release of a suite of integrated OSS applications including the following products:

  • Oracle Communications ASAP
  • Oracle Communications Design Studio
  • Oracle Communications IP Service Activator (IPSA)
  • Oracle Communications Network Integrity
  • Oracle Communications Network Intelligence
  • Oracle Communications Order and Service Management (OSM)
  • Oracle Communications Unified Inventory Management (UIM)

First, and what we believe you’ll be excited to hear about, is searchable documentation for Network Integrity, Network Intelligence, OSM, and UIM that are now available on Oracle Technology Network.

Second, the documentation for Network Integrity, Network Intelligence, OSM, and UIM are now accessible, that is, the HTML-based documentation is in compliance with Oracle Global HTML Accessibility Guidelines (OGHAG), guidelines driven by Section 508 of the Federal Rehabilitation Act and Web content Accessibility Guidelines (WCAG) 1.0/2.0 'AA'.

Third, the documentation for Network Integrity, Network Intelligence, OSM, and UIM are now available in ePub and Mobi format so you can download them to your favorite mobile device.

In response to requests from customers, we added a lot of new content and updated existing content. Here are some of the key accomplishments by product:

Design Studio (these are available on the Oracle Software Delivery Cloud)

  • Developed a new Concepts guide, including a Glossary
  • Developed a new Developer’s Guide
  • Created separate Installation and System Administrator’s Guides

Network Integrity

Network Intelligence

OSM

  • Created a Quick Start Guide for installing OSM on a Windows system, for demo purposes; this document is posted on My Oracle Support and the Oracle Partner Network
  • Improved the XML Import/Export Tool content in the System Administrator’s Guide
  • Improved the XQuery content in the Concepts guide
  • Updated the hardware sizing information in the Installation Guide

UIM

  • Developed a new Security Guide
  • Added information on cooperation framework and sample cartridges to the Developer’s Guide (available on the Oracle Software Delivery Cloud)
  • Added information on concurrent resource allocation to the Developer’s Guide (available on the Oracle Software Delivery Cloud)
  • Added hardware sizing information to the Installation Guide

You, too, can suggest content additions or changes. Send email to cgbu_docfeedback_us_grp@oracle.com.

You will find all our documentation on the Oracle Software Delivery Cloud or check us out on Oracle Technology Network today!

Thank you,
Jodie Wilford, Oracle Communications OSS InfoDev Director

Wednesday Feb 06, 2013

Free Knowledge! Learn Oracle Communications Online Mediation Controller (and more) NOW!

Extra Extra - Read All About It!

I'd like to introduce Leif Lourie, a Curriculum Developer for the Oracle Communications Service Delivery Platform (SDP) products. For the last 8 years, Leif has worked as a Curriculum Developer for many of the telecom-oriented products that Oracle offers. He's been in the telecom industry for about 25 years and has worked also as a software developer, project manager, and architect. He currently creates courses for some of the products within Oracle Communications, namely the Oracle Communications Converged Application Server, Oracle Communications Services Gatekeeper, Oracle Communications Service Controller, Oracle Communications Policy Controller, and Oracle Communications Online Mediation Controller. Leif will share his perspective on developing courses for a product and share what he's done recently for the Oracle Communications Online Mediation Controller. Take it away, Leif!

Developing and supporting software products is challenging in many ways. Every part of our organization can probably name a number of challenges. I have friends in various positions, like engineering, QA, support, and pre-sales, and I have a pretty good idea about some of their challenges. Today, I will tell you about one of the challenges that I have and how I use one of the excellent resources we have at Oracle to address this challenge.

The products I work with are full of features and functions, and it is almost impossible to have full knowledge of even one of these products, let alone create courses that cover all aspects of one product. Well, that is a common challenge for most Curriculum Developers. We just have to divide the information in chunks that will be packaged in basic courses and advanced or specialization courses. But now, we are starting to scratch the surface of the big challenge in my job. What types of courses to create – and when. You see, creating courses is a tough job and we don’t want to waste energy creating courses that no one is interested in. So, how do we know which courses to create? If you ask the people in the field, they want all courses to be available now! Unfortunately, this is not something we can support. So we need more information.

The first real demand for courseware usually comes from the pre-sales people. When they answer a Request For Information (RFI) or a Request For Proposal (RFP) from a customer, one of the standard questions is: What types of courses are available for the products you are offering? But this is still not a good enough source of information. We still do not know if the customer will need this course. Maybe they will only have one or two people working on the administration of the product and they will get enough information for their job from the product documentation.

Another approach would be to talk to our partners. They will be the ones building many of the solutions that will be used by customers. They probably need training to be able to describe, offer, and develop the right solution for the customers. But, many of our partners are already way beyond the basic information we would give them in our courseware, so we might not get enough or the right information from them either.

So, what to do, what to do…???

What if we make basic courseware for some of the SDP products available for free, to gauge the interest of the courseware? Well… we have the Oracle Learning Library, maybe we can use this? Said and done! We now have the first SDP course on Oracle Learning Library – The Oracle Communications Online Mediation Controller - Basic Administration Course.

You may now ask: What is the Oracle Learning Library? The Oracle Learning Library (OLL) allows you to search for free online learning content. The content ranges from videos, tutorials, articles, demos, and step-by-step instructions to accomplish a specific task to in-depth, self-paced, interactive learning modules.

To find the Online Mediation Course on OLL:

  1. Use your favorite browser and go to http://www.oracle.com/oll.
  2. In the middle of the screen, in the search field, enter Mediation and press Enter.
  3. In the list of course modules that is shown, select Oracle Communications Online Mediation Controller - Basic Administration Course, and you will see a description of the course content and you are given the opportunity to download the lessons and labs.

Now, it is possible for you to browse and view many of the course modules without having an account. But to be able to use all the features of OLL it is recommended that you create an Oracle Technology Network (OTN) account. This will give you access to all features of OLL as well as to all other parts of OTN. You can create your account here: https://myprofile.oracle.com/EndUser/faces/profile/createUser.jspx

After this you may browse all of the OLL resources. What are you waiting for? Learn more!

There is enough knowledge at OLL to keep you busy – learning – for a loooong time.

Thursday Jan 31, 2013

About the Pricing Design Center User Productivity Kit

Learn about Oracle Communication's first User Productivity Kit module for Pricing Design Center.[Read More]

Friday Jan 18, 2013

Welcome to the Oracle Communications Documentation and Curriculum Blog!

This is an introduction to the Oracle Communications Documentation and Curriculum blog - who we are, where we came from, and where we're going![Read More]
About

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

Search

Categories
Archives
« May 2015
SunMonTueWedThuFriSat
     
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
      
Today