Tuesday Dec 24, 2013

New Tech, New Challenges: The Oracle Communications WebRTC Session Controller Documentation

Our last blog of the year is written by John Francis, one of our Technical Writers who's been working on the Service Delivery Platform writing team for nearly two years. This blog is about his experience leading the documentation work for one of our new products, the Oracle Communications WebRTC Session Controller. His past projects include Oracle Communications Services Gatekeeper 5.1, for which he wrote this blog entry, and Oracle Communications Billing and Revenue Management Elastic Charging Engine. John is currently working as a documentation Project Lead for a large, distributed telecom project whose release date is yet to be decided. In addition to documentation projects, John enjoys workflow automation programming because, and these are his words, "he's both lazy and forgetful." I'm sure you'll enjoy this piece as much as I did given John's natural writing style as well as his sense of humor which comes through loud and clear in his writing. Thanks to John for this enjoyable blog and to the other contributors from my team who submitted blog entires this year!

Cheryl Lander, Oracle Communications InfoDev Senior Director

As the Services Gatekeeper 5.1 project was drawing to a close in May 2013, another development project had been well underway since September 2012: WebRTC Session Controller.

What’s WebRTC Session Controller you ask? Basically, it’s a gateway between the Google-created Web Real Time Communication protocol, which lets you place video and audio calls between two browsers using no proprietary plug-ins, and the vast expanse of existing Telecom equipment operating via Session Initialization Protocol (SIP)/Session Description Protocol (SDP) networks. In short, instead of just being able to place a call from one browser to another browser, WebRTC Session Controller lets you seamlessly place a browser call to your Aunt Maude’s 1972 avocado Princess phone. My colleague, Leif Lourie, has provided an excellent overview of WebRTC Session Controller in his own blog entry on Oracle's “Transfer of Information” culture, so I won’t retread the same ground, because, as Leif points out, this is not a blog entry about the product, it’s a blog entry about the documentation effort for the product.

Catching Up with the Development Team

After initial feature analyses and level of effort scoping by the documentation lead, we gathered together a veteran five-person InfoDev team with core competencies in the various required domains. As sometimes happens, the team members were finishing off other obligations, and arrived a bit late to the project. In fact, as we started our planning, we were informed that the project was already eighty percent complete, so the pressure was on.

Now oftentimes Oracle Communications products are incremental updates and point releases which build upon existing documentation libraries. However, in the case of WebRTC Session Controller, or Web Signaling Engine as it was initially known, we were actually working on a brand new project in a brand new cutting edge field. With that in mind, we had a bit of research and learning to do in the following areas:

  • WebRTC concepts and implementation
  • General Web development concepts and methodologies with an emphasis on HTML5
  • SIP and SDP concepts and implementation
  • WebRTC Session Controller concepts and implementation

Web development proved to be a new topic for most of the team, since most of us were most familiar with enterprise Java development—we spent several sessions going over the practicalities and pitfalls (how many browsers should this project support?) faced by typical web developers, as well as the types of information they would most value when working with WebRTC Session Controller. In addition we forged ahead with a complete audience analysis so that we could write at the appropriate levels in each of our assigned guides.

So informed, and in conjunction with Product Management, we decided on the following deliverables:

  • A Concepts Guide describing the key concepts of WebRTC Session Controller. This guide is targeted at all user levels—basically anyone who needs a high level overview of the product’s functionality.
  • An Installation Guide describing preparation, installation, and configuration. This guide is targeted at system administrators and installation engineers and requires a strong background in networking concepts and general operating system tasks.
  • An Administration Guide detailing important ongoing administrative tasks. This guide, obviously, is targeted at WebRTC Session Controller administrators, and requires technical familiarity with WebLogic server concepts.
  •  A Web Developer’s Guide describing how to build applications using the WebRTC Session Controller JavaScript library. This guide is targeted at third-party Web application developers who want to create WebRTC-enabled applications. A solid background in Web development is assumed.
  • An Extension Developer’s Guide describing how to integrate WebRTC Session Controller with a typical telecom SIP backend. This guide is targeted at Telecom infrastructure engineers who need to integrate background telecom protocols into WebRTC Session Controller. Detailed knowledge of SIP and SDP, as well as fluency in Java are assumed.
  • A Statement of Compliance describing the products adherence to IETF standards. This guide is targeted at Telecom engineers who need to know exactly what standards are supported by the project.
  • A Security Guide describing how to securely configure WebRTC Session Controller. This is an important guide enabling system administrators and installation engineers to secure a WebRTC Session Controller system. Although not exhaustive, it covers the most significant areas.

We also determined that we’d need to scrub through comments in the JavaScript and Java source and deliver Configuration API and JavaScript API references as well as write a set of release notes.

With a roadmap before us, we dug in and started our work…

The Acquisition and Integration

As with many of its peers, Oracle relatively frequently acquires companies to further its business objectives. In early 2013, Oracle purchased Acme Packet, a vendor of session border control technology, an event to which some writers in InfoDev only paid brief attention. After the regulatory blackout period lifted, however, and the WebRTC Session Controller development team started meeting with the Acme Packet development team, it became apparent there were valuable Acme Packet technologies that the Oracle development team could integrate into WebRTC Session Controller which would considerably enhance and extend its functionality. Two particular features were of great interest:

  • A high-performance media stream routing system for audio and video compression formats.
  • An integrated Traversal Using Relays around NAT (TURN) system allowing users behind Network Address Translation (NAT) firewalls to reach out and “find” other users themselves hidden behind NAT firewalls (for more information on TURN, see this excellent explanation by Sam Dutton).

Both development teams immediately went into refactoring mode, and we found our deadlines extended (much to our relief).

While the technical issues with the integration were complex, the actual impact on our documentation set appeared to be relatively minor. In fact, the only doc that required significant rework turned out to be the Installation Guide. Since the Acme Packet-acquired documentation used a completely different format from the Oracle Communications documentation, we decided it would make the most sense from a customer point of view if we created a single Installation Guide covering both the Oracle Communications Signaling Engine component and the Acme Packet Media Engine component (both of which, together, comprise the entirety of WebRTC Session Controller). We then engaged with the Acme Packet documentation and development teams to find out the scope of a typical Media Engine installation and revised our plans for the Installation Guide.

End Game

The extension of our deadlines mentioned previously also enabled writers to improve other documents in the core library, including, Administration, Web Application Developer’s, Security, and Extension guides: we were able to conduct additional technical reviews as well as greatly coveted editorial passes. The Web Application Developer’s Guide, especially, went through additional valuable rounds of structural as well as content and technical edits, leading to a much improved final document (you can take a look at it here, and let us know if you agree). However, the integration issues began to affect the availability of information for the Installation Guide. Issues were being found and resolved almost up until our final deadlines.

In spite of the churn, and because of the flexibility and excellent support from the Acme Packet documentation and development teams, we were able to pull all of the relevant information together and, even with deadlines looming, run three separate technical reviews. The Installation Guide was pulled together and cleared both Acme Packet and Oracle Communications quality assurance teams. The only thing remaining at that point was the creation of what turned out to be a delightfully short set of Release Notes containing a list of features and a handful of known issues and their workarounds. And once these Release Notes were complete, we notched up yet another release.

Future Plans: Documentation Integration

The one thing that we weren’t able to address was the disparity in formats between the Acme Packet documentation and the Oracle Communications documentation. Each company uses completely different technologies to produce output, and that output looks completely dissimilar. In addition, Acme Packet’s Media Engine component is only a small subset of Acme Packet products, and for the benefit of documentation management, Acme Packet produces a single documentation set that covers all of their extensive product line. That means that we were forced to use some rather awkward references when we wanted to direct a user to additional information in a particular Acme Packet guide. References such as, “For more information on Media Engine tuning parameters, see the Oracle Communications Net-Net OS-E System Administration Guide,” were common, and significantly confusing, given the heterogeneous nature of the two documentation sets, but entirely unavoidable given our time constraints.

To solve such issues going forward, we are considering the following work depending upon timelines and staffing resources:

  •  Isolating the Media Engine specific content in the Acme Packet documentation.
  • Evaluating the Acme Packet documentation and scoping the work involved in porting it to the Oracle Communications documentation structured templates (not a trivial undertaking).

Of course that will be in addition to new feature work, and is dependent to a certain extent on departments outside of our control. At the very least, though, it should make for few dull moments in the 8.0 release.

We Value Your Feedback

You can find the Oracle Communications WebRTC Session Controller documentation here.

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

·       Email cgbu_docfeedback_us_grp@oracle.com.

·       Post a comment on this blog.

Thanks for reading!


The image used in this blog entry was created by Adam Foster and is licensed under Creative Commons 2.0. The image was cropped slightly but no other changes were made. No relationship exists between Mr. Foster and Oracle Corporation and no endorsement on his part is implied or expressed.

Friday Dec 20, 2013

The Transfer of Information Culture

The author of this blog is Leif Lourie, a Curriculum Developer supporting the Oracle Communications Service Delivery Platform (SDP) product line. For the last 8 years, Leif has worked as a Curriculum Developer for many of the telecom-oriented products from Oracle. He has been in the telecom industry for about 25 years and has also worked as a software developer, project manager, and solutions architect. He is currently working on courseware for a recently released product, Oracle Communications WebRTC Session Controller. In this blog, he talks about the transfer of information (TOI) culture that he experienced at BEA, something that has carried over into the Oracle Communications team.

Cheryl Lander, Oracle Communications InfoDev Senior Director

Oracle recently released a new product. While this blog is not really about products, I will still give you a bit of information about it before I delve into the main topic of this blog: the TOI culture.

About the WebRTC Session Controller

The WebRTC Session Controller is a very interesting product which implements and enhances an emerging standard that will soon be used daily by many, many people around the world. The emerging standard is called WebRTC which is translated as “Real-Time Communication for the Web.” The primary goal is to enable voice, video, and data communication within a normal web browser.

Instead of using some specially installed software on your computer, you will be able to use Chrome or Firefox to make phone calls, with or without video, combined with chat and file sharing.

This technology is already available in the latest versions of the Chrome, Firefox, and recently Opera browsers, but very few people know that it is there. We will soon start to see web sites using these built-in features.

Even though it is very cool to be able to set up a video call directly between browsers, this will not be widely used until you can use it to call fixed line and mobile phones.

Here is where the new product, Oracle Communications WebRTC Session Controller, comes into play. Not only do we supply an SDK that makes it easier to build web applications using the WebRTC features in the browsers, we also supply the back-end infrastructure to integrate with the “real” phone network. This means that it is possible to use your browser to call to “real” telephones.

However, since this blog is not really about products, I will point you to other official resources for technology and product information.

The TOI Culture

What I really want to talk about is the Transfer of Information (TOI) culture that exists in a particular part of Oracle Communications.

Let me back up a little bit… As everybody knows, Oracle is growing by acquisitions. Most companies that are incorporated into Oracle lose their old culture and the people are being spread out and mixed with people from previous acquisitions. But very often, bits and pieces from the old culture survives and continues to thrive.

The Transfer of Information is such a piece. So what is it?

It started many, many years ago as a forum where the engineers of a new product transferred internal information to the support engineers to prepare them to take care of customer cases after a product was released. But since these sessions contained so much valuable information, the audience grew to include the pre-sales and consulting organizations. Suddenly there was a need to add marketing information about why this product is important and to add hands-on practices to be able to demonstrate the product’s functionality and value.

So, within this particular part of Oracle Communications there is almost always a one-week TOI, where most parts of the new product or new release is described in detail.

A great spin-off of this is that Oracle people, from all parts of the world, working in the same product space, actually get to meet each other!

To me, the breaks are as important as the sessions. To put faces to the people I email and chat with  all over the world is very valuable. At the TOI for Oracle Communications WebRTC Session Controller I met colleagues from Norway, Austria, France, Mexico, China, Israel, USA, Brazil, Australia, South Korea, and Canada. And I am certain there were people there from other countries as well. I met many of the engineers that have been involved in developing the product. I met people from Support, Pre-sales, and Consulting that were all preparing to support this product in their line of work.

And, of course, many of the participants (product ambassadors) go back to their home offices and conduct mini-TOI’s with their closest colleagues. That way the correct information about the new product and new features is spread out all over the world in a timely and efficient fashion.

The Transfer of Information culture is extremely valuable and it helps us keep up with the fast moving technology, expand our internal network, and get us motivated to continue to be a valuable member of this worldwide TEAM!

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

Thanks for reading!

Friday Dec 06, 2013

Managing Oracle Communications Applications with Enterprise Manager Cloud Control

I'm very excited to intoduce a new InfoDev blogger. Meet Chet Liew, Principal Technical Writer for Oracle Communications based in Bend, Oregon. His previous roles at Oracle include time as a QA Engineer and Product Manager working with BRM and OSM. Currently, he writes documentation for our Service Delivery Platform and Application Management Pack products while also assisting in the provisioning and management of InfoDev server environments used by technical writers and curriculum developers. I hope you'll enjoy his blog on his approach to documenting one of our new products, the Application Management Pack and the challenges he faced. We welcome your feedback, either in the form of confirmation of his approach or to tell us an approach that would work better for you.

Cheryl Lander, Oracle Communications InfoDev Senior Director

EM + Oracle Communications 

Oracle Communications solutions usually leverage more than just our business unit’s applications. They also utilize some of Oracle’s best software and hardware assets like WebLogic Server, Siebel CRM, and Oracle appliances providing comprehensive solutions to our customers.

Applications Management Pack for Oracle Communications (AMP) reduces overhead for customers implementing multiple Oracle products. It adds the ability to install and manage our applications to the already available Oracle Enterprise Management Cloud Control capabilities for managing hosts, databases, domains, and other enterprise applications.

Multi-application environments present not just management challenges for our customers and partners. They also present a unique challenge for the Information Development (InfoDev) team. Our task, when documenting products like AMP, becomes a balancing act of giving our customers adequate information to use the product efficiently, but also making use of existing documentation. Our desire is not producing books filled with redundant information available elsewhere, requiring maintenance and updating as new versions of our products (and documentation) are released.

The AMP documentation follows a philosophy of providing enough information for users familiar with the supported Oracle Communications applications and Enterprise Manager Cloud Control to accomplish the tasks possible with the product. The documentation aligns with the product’s goal of streamlining the provisioning (installation), configuration, and monitoring of supported Oracle Communications applications.

Such a philosophy makes some assumptions of our end users. We assume that the end user performing the documented tasks already understands Enterprise Manager Cloud Control and Oracle Communications applications installation and where to go to get more information. The expectation is not that a user can use the AMP documentation alone to install, for example, an Order to Cash environment. The documentation requires a resourcefulness in the reader to access the referenced documentation to do what’s required.

One of the other goals of the documentation is to provide tasks in a modular fashion to the user. The number of functions that can be accomplished using the AMP plug-in in Enterprise Manager Cloud Control is vast. Customers may implement some plug-in functions while not using others at all. The documentation, much like the plug-in, is designed for varying degrees of usage, with an emphasis on referencing other documents when needed and allowing users to accomplish tasks directly from the table of contents.

Documentation for cross-product solutions continues to evolve and improve as such offerings become more the norm. There are areas of improvement that need to be explored. For example, we can do a better job of tailoring documentation for different types of end users. As part of our documentation process, InfoDev undertakes an Audience Analysis for each product. We glean information from internal and external users of our documentation for improving our end product. Expanding this process to cross-portfolio solutions is an interesting challenge for us to meet but I don’t doubt we’ll attack it with enthusiasm.

The AMP documentation is written from the perspective of a single type of user performing the explained actions. An Audience Analysis of our AMP customers will likely reveal that there are many users instead of just one. Future editions of the AMP documentation will evolve toward better delineation of tasks for different types of users. After all, in the field it’s very unlikely that the Enterprise Manager Cloud Control administrator at a large service provider is the same person as the BRM administrator.

Documentation improvements of this type require collaboration between every entity that touches a product like AMP. InfoDev looks forward to working with our internal and external customers to continually improve our products.

You can find the documentation for Application Management Pack for Oracle Communications on the Oracle Technology Network here.

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

Thanks for reading!


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


« December 2013 »