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!

Legalese

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.

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
« December 2013
SunMonTueWedThuFriSat
1
2
3
4
5
7
8
9
10
11
12
13
14
15
16
17
18
19
21
22
23
25
26
27
28
29
30
31
    
       
Today