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.

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!

Friday Oct 04, 2013

Mentoring the Technical Writers of the Future

Today's blog is from one of our technical writers, Caroline Wissing, from the Service Fulfillment writing team. Caroline has been a technical writer at Oracle Communications for just over three years. She has worked in documentation since 1999 and has mentored many new writers during those years. She took on the role as the primary mentor for the 2013 technical writing interns, who were hired through Ottawa’s Algonquin College co-operative education program. Thanks, Caroline for this blog as well as your support and mentorship of our interns!

Cheryl Lander, Oracle Communications InfoDev Senior Director


 

Kayla and Rachel’s internship has ended and we were sad to see them go. As our previous intern, Carly, was before them (and is now permanently), they were an asset to the organization during the four months they worked for the Oracle CGBU Information Development (InfoDev) organization. At least the blog post that they co-wrote remains with us to remind us of their contributions, and the experience and knowledge they gained during their time at our office.

But let’s not forget that experience and knowledge go both ways. This was our second time, here in Ottawa, hiring and working with interns and I like to think we learn a little from each experience. In the spirit of reciprocal blogging, I thought I’d chronicle this same journey, except from a mentorship perspective. Each section below details an aspect of the mentorship role and then outlines a few things that experience has taught us over the past two internships.

Interviewing and Hiring

The first step in the process is before the mentorship begins, but is also the most important: hiring the right people.

When we receive the resumes of potential internship candidates, there are typically several resumes to peruse leisurely, from which we can select people to interview. We learned not to be too leisurely in the perusal, however, because if we dragged our heels, we risked the hottest prospects getting snatched up by companies that chose to interview candidates early.

In preparation for interviewing the three or four candidates we’d chosen, we reviewed their resumes in more detail and prepared a set of questions, some of which were generic and some of which we tailored to each individual’s knowledge and experience. We also devised a short writing test with sections that measured skills such as organizing content, writing procedures and understanding the difference between conceptual and procedural information.

After the fun of meeting and interviewing was over, the final selection process started. We ranked the candidates based on the criteria available: resume, interview and test.

This can be tricky because one candidate can have a strong interview but a weak test, and vice versa. Ranking them was based on performance but also on our instinct and their potential. We solicited feedback about the resume and test portions from the wider team. InfoDev leads from the Editing, Architecture and Production departments had the opportunity to weigh in, as well as the management team.

What We’ve Learned

We have learned to trust our instincts about who would be a good fit for our team. Someone who can put procedure steps in the correct order on a test but comes to the interview wearing a tinfoil hat and talking to an imaginary camel is not likely the better candidate. (For the record, neither Rachel nor Kayla wore her tinfoil hat to the interview.)

Preparing and First Day Jitters

There are several things you can do to help interns feel both welcome and better prepared to jump into life at Oracle. They’re here for a good time, not a long time, so the quicker you can get them up to speed, the quicker they can get to work with confidence.

  • Order equipment early and set it up ahead of time. New hires learn about Oracle process by doing a lot of their software setup themselves. However, interns need to get moving fast. It saves time if you can get them in the system and have their laptop ready for them to start working within their first or second day. If their equipment hasn’t even arrived, you risk that they’ll be sitting around idle for days doing nothing more than reading a paper copy of the Oracle Style Guide. They might not come back the following week.
  • Provide the new hire checklist. Whether you print it out or email it to them, have it ready. Modify it if you’ve done any of the tasks for them.
  • Provide a list of acronyms. When interns attend their first meeting and hear nothing but a string of letters, much like this: “The OSM BRD for SR3 with updated RMIs and FEATs is up on the TWiki along with FDDs and TDDs, so InfoDev can create CPs with more accurate LOEs by APM Gate 3,” their heads are apt to explode. Sure we know what that means, but it might as well be Sanskrit to an InfoDev newbie. Remember, they were students the week before and might never have worked in documentation.
  • Provide a list of useful links. Despite efforts to improve navigation, the InfoDev Twiki (the department’s knowledge base) can be a labyrinthine warren and if you go down the wrong rabbit hole, you might never find your way back, or the information you’re searching for. Providing this list helps interns quickly add important links to their browser’s bookmarks list.
  • Make a list of tasks. Knowing what tasks you need them to do, at least for the first month, lets you get them busy and keep them busy. Make sure you give them simple tasks first until they get comfortable with the documentation and process. We created a high-level schedule for their tasks and assigned a mentor for each task. Although this work plan needed to remain flexible to accommodate changing priorities, it helped to guide the intern’s work for the duration of their term.

What We’ve Learned

According to feedback from Kayla and Rachel, and from Carly (who didn’t get one), the most essential early tool we provided for them was the list of acronyms. It’s easy to forget how little meaning there is in an average meeting for anyone who doesn’t know these definitions.

Transferring Knowledge

This internship is for their benefit as well as ours. Never is this symbiotic relationship more important than in the area of knowledge transfer. We could give them just enough information to complete each simple, discrete task, or we could give them the broader perspective. For the latest pair of interns, in their first few weeks, we provided lots of instruction, including formal meetings about the following topics: overview of the APM release lifecycle; using Oracle Review; the bug process; working with RSB; and working with the editor, architect and production team.

One-on-one meetings with their mentor (hopefully) allow interns to ask any question in a comfortable and supportive setting. They also come to the end of their internship with knowledge that’s transferrable to other jobs in the technical writing industry.

What We’ve Learned

Understanding the big picture helps interns integrate more quickly and participate more actively in team meetings.

Providing Support without Doing the Work

No one wants to be micro-managed, not even interns. If given the right task at the right time in their internship, they can accomplish a lot on their own. As long as an identified go-to mentor is approachable and readily available, it’s important to let them use their accumulated skills and new knowledge to figure things out independently.

What We’ve Learned

Tailor the mentorship style to the intern’s individual learning style. Some people like to grapple with a problem, devise a solution, and then solicit feedback, while some people would rather ask lots of questions upfront before they feel comfortable making changes to documentation. Either way, the mentor should check in with interns daily to make sure they aren’t stuck or overwhelmed.

Goodbye!

We hope Kayla and Rachel left Oracle with invaluable knowledge and experience that they carry with them to their next opportunity. In turn, we enjoyed four months of their great company and hard work.

We wish them well!

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 Aug 30, 2013

Services Gatekeeper 5.1: A Large Documentation Effort for a Feature-Rich Platform

Today's blog is from one of our technical writers, John Francis, from the Service Delivery Platform (SDP) writing team. He was the documentation project lead for the most recent release of the Oracle Communications Services Gatekeeper and shares information about the product and the docs below. John is relatively new to the our team - he started in March 2012. He has a fondness for electronic gadgets and Boston Terriers, and can be found in the shoe department at Nieman’s watching his wife shop most weekends. He has a keen sense of humor, which you'll soon experience. I hope you enjoy reading his blog!

Cheryl Lander, Oracle Communications InfoDev Senior Director

Thanks very much, Cheryl! By way of introduction, Oracle Communications Services Gatekeeper lets telecom service providers grant their partners access to myriad telecom network services via easy-to-use, standardized interfaces known as facades. Its feature set includes full partner and network control, finely grained service level agreement support, and almost unlimited extensibility potential, along with carrier grade reliability and scalability.

After more than a year of concerted development effort, on May 28th, 2013, Oracle released a comprehensive upgrade for Services Gatekeeper that provides the following enhancements:

  • Simplified telecom partner management, including policy provisioning, partner on-boarding, and business process automation via a brand new web-based partner portal application
  • API reporting capabilities allowing telecom customers to see detailed trends at a glance
  • An expanded repertoire of communications services including support for QoS, Email, Address List Management, Bulk Messaging, and Application Subscription Management
  • Enhanced existing Services Gatekeeper APIs in the areas of Charging, Unified Messaging, Mobile Policy and Authorization and Authentication, via OAuth and Anonymous Customer References
  • Expanded platform support, including ready-to-use integration with Oracle Communications Online Mediation Controller, Oracle Communications Policy Controller, as well as Siebel CRM, via SMS and Email

As you can see from that list, the modest “dot one” version increment belies a wealth of expanded features and complexity, all of which it was incumbent upon SDP InfoDev to document.

Project Documentation Accomplishments

As often happens, because of the multiplicity of projects and responsibilities, InfoDev arrived a bit late in the development of Services Gatekeeper 5.1. In addition to the late start, the writing team faced the following challenges:

  • With a lead writer new to Oracle and Services Gatekeeper, the lead had to learn the CGBU InfoDev organization's enterprise documentation standards, and ramp up on the extensive processes devoted to delivering quality technical documentation.
  • Services Gatekeeper is a huge product with broad areas of functionality. It’s difficult to master some of the core concepts, let alone the entire product.
  • The documentation set has expanded over Gatekeeper’s decade plus service life. Writers had to carefully research the two thousand plus pages of documentation to identify which documents were affected by which features.
  • We’ve got only two hard-working editors, whose time is continually spoken for and whose schedules were at odds with Services Gatekeeper’s milestones.
  • Development goals were fluid during the course of the project with features prioritized and deprioritized on a regular basis.

We were able to mitigate those factors by assembling a team of veteran technical writers (along with one scrappy upstart) who were able to dig into the Services Gatekeeper documentation library, understand its scope, assimilate the new features and come up with a flexible documentation plan. As with all large scale, long term projects (this one spanned more than a year), we needed to remain agile, regularly interfacing with the development team, and trying to stay on top of the project. In addition, we counterbalanced the lack of editorial support by farming out our documentation to our willing colleagues for peer review.

Project Documentation Extended Accomplishments

At the beginning of the project, our goals were initially modest. We, of course, wanted to document all features, as well as provide editorial support for the two Javadoc systems that ship with Services Gatekeeper. As the project evolved, and the timeline expanded to encompass unforeseen obstacles and integrate late-breaking critical features, similarly, InfoDev expanded its scope. In the end, the team met the following additional expanded goals:

  • Created a new Security Guide per Oracle’s latest guidelines
  • Produced and delivered a revised and reorganized OAuth guide
  • Reviewed more than 650 Javadoc source files, making edits to approximately 195 of those
  • Worked extensively with the Portal team, not only on online help for the application but also on workflow reviews and bug hunting
  • Addressed more than thirty incidental documentation enhancement requests requested during the product lifecycle
  • Closed out bug backlogs from earlier versions and made it to GA with no outstanding issues

Our fantastic production team also enabled enhancements that required no effort from us, the most impressive of which were:

  • ePub and Mobi ereader formats, should you wish to review our documentation on your tablet or ereader
  • A much requested search feature, capable of searching our documents either at the library or single document level
  • And, finally, on a nerdy level, a new source control system (Subversion, or SVN) that enabled us to build our documents whenever our hearts desired

Future Plans for Services Gatekeeper Documentation

Naturally, time stands still for no software product, and Services Gatekeeper is no exception. Even as I write this, product management and development are in the planning stages for the next version, and InfoDev is no different. Some initial goals that we’re hoping to meet for the next version include:

  • Having the large (22 systems) documentation library reviewed by our content architects and identifying opportunities for simplification and consolidation
  • Working with Product Management and Consulting teams to identify areas in the documentation which need to be improved or expanded
  • Identifying tools that will help improve the quality of our documentation with little to no capital investment or time commitment

We Value Your Feedback

If you're an Oracle employee, you can find the Services Gatekeeper 5.1 docs here.

As always, we’d love to get feedback! If you’ve got content additions or changes, you can post a comment on this blog or send email to cgbu_docfeedback_us_grp@oracle.com.

Finally, you can find all our documentation on the Oracle Technology Network.

Thanks for reading!

Friday Aug 23, 2013

Oracle’s Internships for Technical Writers Look to the Future

This is the second year in a row that we've had the fortunate opportunity to hire technical writer interns from Ottawa, Canada's Algonquin College's post-graduate Technical Writing program. Kayla Robinson and Rachel Rosenfeld have been on board for four months (May through August) and during that time, they've learned about tech writing from the experts on our team and we've use their skills and enthusiasm to get work done--what a perfect match!

First a bit more about Kayla and Rachel. They both have arts backgrounds: Kayla majored in English at Carleton University and Rachel majored in history at Dalhousie University. Kayla enjoys creating graphics and writing social media pieces. Rachel enjoys learning about new products and software applications. During their time at Oracle, they worked on AIA, IP Service Activator, UIM, OSM, and MSS projects.

Today's blog is all about their experiences and I'm sure you'll enjoy reading it. This also is a good reflection of the things we do on our team to ensure our team members continue to develop their skills, share their experiences, and focus on creating high-quality content. Thanks to Kayla and Rachel for a great blog and for four excellent months of work - best of luck to you in your tech writer careers.

Cheryl Lander, Oracle Communications InfoDev Senior Director

Oracle’s CGBU Information Development (InfoDev) team provides quality internships for new technical writers, like us, who want to gain real world experience in the workplace. Fostering a mutually beneficial relationship with Algonquin College’s technical writing program in Ottawa supports the local community and new professionals looking for industry training.

This blog post is the culmination of our efforts to select the top 5 reasons why our internship has blown our socks off:

1. Participating in Brown Bag Presentations

Brown Bags are not a packed lunch that technical writers bring to work. We are much more likely to be found getting sushi takeout or stopping by one of the gourmet food trucks in downtown Ottawa. Oracle Brown Bag presentations are lunch-and-learn web conferences that focus on a variety of topics.

Brown Bags explore new product innovations, current projects, customer feedback, and tips on documentation, courseware tools, and processes. Some really useful topics included Doc Bug Best Practices, How Audiences Read, and tips on how to take advantage of features in our FrameMaker authoring tool.

2. Collaborating with a Global Team of Technical Writers

Meet the diverse team we collaborate with:

  • Technical experts have specialized knowledge that range from fixing computers to programming languages.
  • Tool gurus are willing to take the extra time to help you when you get stuck on a tools issue. When you have stumbled into the Bermuda triangle of software errors and cannot find your way out, your fearless tool guru will show you the path.
  • Mentors are the experienced writers who are willing to instruct you on how to perform the tasks necessary for job success. Our mentors really helped us adjust to the company processes. They even provided us with a cheat sheet of useful links and tips. Definitely a must-have.
  • Team Leads and Managers have calendars with schedules more complex than any Rubix cube puzzle, and somehow they still have time for us! We haven’t figured out quite how they manage to do this, and we are inherently suspicious of their super-human abilities.
  • Documentation architects focus on structuring information in a logical and consistent way for a user. Our documentation architect visited Ottawa and held focused learning sessions about document structure and writing for different audiences. To learn more about documentation architecture, read Scott Miller’s blog post: Online Help and the Epic BFFL Throwdown of the 90s.
  • Editors fokus, among other things, on making our writing klear and task-oriented instead of describing softwear featyours. Our editor, Bob, holds an informal meeting every Friday where he updates the team on unit-wide developments, addresses questions, and occasionally we get to hear his cat Jason in the background. Wut wood we do without our editor?
  • Courseware Developers are knowledgeable about the products and can be a good resource. They appreciate it when you perform usability tests on courseware and troubleshoot the courseware in a real-time training environment.

3. Working with Industry Tools

There are many tools available for writers. Our toolkit is definitely more extensive thanks to Oracle, and you can check out our favorites below:

  • Structured FrameMaker: A popular structured authoring application that uses tagged mark up to create consistently structured documentation.
  • Oracle Review is an internal tool where writers post their drafts and invite reviewers to pin comments to the posted draft.
  • Graphics tools: Microsoft Visio makes it possible to create flow charts to illustrate complex concepts, and we use Snagit to snag awesome screenshot captures and painlessly edit them.
  • Version-Control: Version control software keeps a history of when documents are modified and provides controls to make sure that multiple authors aren’t working in the same book simultaneously. It also provides backup so writers don't lose their work, because we have writers in California (earthquakes), Texas (tornadoes), and Canada (maple syrup shortages).
  • TWiki is an internal InfoDev wiki where guidelines about writing style, process, content, structure, and procedure are all documented. We would have been lost without this oft-bookmarked and frequently accessed resource.

4. Learning the Company Values

Blending in with a company’s corporate culture is a significant part of succeeding in a work placement. We have learned two things about Oracle:

  • Oracle values technical documentation: We heard stories about companies where writers spent their days chasing down developers who had no time for questions. At Oracle everyone was more than willing to provide us with information, patiently answer our questions and provide us with the resources at their disposal.
  • Oracle promotes working independently: After our initial two weeks of training, learning processes and downloading tools, we were expected to work with minimal supervision. We were provided with a work schedule, encouraged to ask questions when we were unsure and expected to provide status updates and attend meetings, but we weren’t micro-managed. Being trusted to work independently encouraged us to take initiative in ways that might not have been possible if a manager had been hovering over our shoulder. We were accountable for our time at work, and this trust encouraged us to work hard.

5. Engaging Tasks

“Working hard, or hardly working?” Well we know for a fact that we were working hard, but our favorite tasks hardly seem like work. Here is a list of the tasks we enjoyed most:

  • Fixing bugs: When a documentation error or required update is flagged in the internal database, we call it a documentation bug. Fixing documentation bugs involves putting on your Sherlock Holmes hat and doing some detective work. Research and tracking down subject matter experts can take time, but it is worth it in the end when you can go into the bug database and change the bug status to a satisfying 89 to indicate you have solved the problem. For example we might say, “Sweet. I 89ed that doc bug all the way to Quality Assurance. Take that.”
  • Writing Content: Writing content is what comes to mind when you think about technical writing. In reality, there is so much else involved in the average workday. After all the planning , researching, converting documentation, attending meetings, and all the other tasks that take up your day it is nice to sit down and write content.
  • Creating Graphics:

A key aspect of communication is maintaining an open dialogue, and continuously eliciting feedback. When an international company like Oracle encourages two technical writing interns to contribute to the company blog by writing about our experience as interns, we can provide guidance and tips to the next generation of interns by sharing our experiences of a memorable summer at Oracle.

Please help us by sharing your best advice, tips, or personal anecdotes for new interns with a comment!

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:

Thursday Aug 08, 2013

Complete, Integrated, Configurable: RODOD

Jodie Wilford, Oracle Communications InfoDev Director, has written a few blogs for us. She first wrote about updates to the OSS documentation set, then about the Oracle Application Integration Architecture for Communications Overview course. In this blog, she introduces content that's available about one of the Oracle Communications solutions, RODOD.

Cheryl Lander, Oracle Communications InfoDev Senior Director
 

Oracle Communications Rapid Offer Design and Order Delivery

 

Oracle provides telecommunication service providers a fully-integrated, product-based Rapid Offer Design and Order Delivery solution (RODOD).  This solution enables service providers to rapidly design and introduce offers, capture and fulfill orders efficiently and accurately, and provide visibility across the full order lifecycle.

Oracle Communications RODOD solution provides:

  • Faster time to market with integrated end-to-end offer design configuration
  • Shorter order cycles with complete visibility across the order lifecycle
  • Reduced operational cost through advanced order management capabilities and integrations

RODOD is a comprehensive solution consisting of Oracle’s Product Hub for Communications, Siebel CRM, Oracle Communications Order and Service Management (OSM), Oracle Communications Billing and Revenue Management (BRM), and Application Integration Architecture (AIA) for Communications.

Learn more about the solution in the RODOD Introduction and Overview online courses now available for Oracle employees and partners.

RODOD Introduction Course Overview

This course provides an introduction to the Oracle Communications RODOD solution using real world business scenarios covering the functional areas of offer design, order capture, and order delivery.

Course Audience: The course is the starting point for anyone wanting to learn about the RODOD solution.

Course Objectives: After completing these courses, you should be able to:

  • Describe RODOD
  • Describe business scenarios

RODOD Overview Course Overview

This course provides an overview of the RODOD solution. You learn about the challenges of order management and how RODOD handles these along with the solutions and benefits.

Course Audience: The course is the starting point for anyone wanting to learn about the RODOD solution.

Course Objectives: After completing these courses, you should be able to:

  • Describe the RODOD solution:  
    • The challenges of order management and how RODOD handles these 
    • The solution benefits and key differentiators
    • Describe the functions and role of applications in the RODOD stack
  • Describe real-life use cases and how RODOD manages these functions

Accessing these courses (Oracle employees and partners)

To access these courses, go to Oracle iLearning and search on "Introduction to RODOD" (30 minutes) and "Rapid Order Design and Offer Delivery (RODOD) Overview" (51 minutes).

Note: When you get to the demo portion of the "Introduction to RODOD" course, you need to click on the link to continue.

Go here for more information on RODOD.

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:

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 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
http://www.oracle.com/technetwork/systems/index.html

OTN Garage (Official blog of the System Admin and Developer Community of OTN)
https://blogs.oracle.com/otngarage/

Solaris 11: Basic Administration
http://www.oracle.com/technetwork/articles/servers-storage-admin/basic-s11-operations-1871467.html

Solaris 11: Image Packaging System
http://www.oracle.com/technetwork/articles/servers-storage-admin/command-summary-ips-1865035.html

Solaris 10 - Oracle Linux Command Comparo:
https://wikis.oracle.com/display/OTNTaskFinder/CommandComparo+Home

Rosetta Stone:
http://bhami.com/rosetta.html

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:

Thursday Apr 18, 2013

BRM Patch Set Documentation: What You Might Not Know

About Oracle Communications Billing and Revenue Managment (BRM) Patch Sets

Today's blog is about BRM patch sets and was written by Venkat Dharmapuri, Principal Technical Writer on our India team. Venkat is the Project Lead for BRM 7.4 and 7.5 patch set documentation so is perfectly positioned to provide this content. He works with various writers, editor/architects, and the project team to define the documentation strategy and deliver to plan. Thanks to him and everyone he works with for ensuring our documentation stays in sync with the product patches.

Cheryl Lander, Oracle Communications InfoDev Senior Director 

What are BRM Patch Sets?

Oracle Communications Billing and Revenue Management (BRM) patch sets are planned releases that follow an approximate three-month delivery model. The Patch Set release includes features and bug fixes. The management team decides on the features targeted for a particular patch set release based on customer requirements and feedback.

How Does the Oracle Communications InfoDev Team Contribute to BRM Patch Sets?

InfoDev supports BRM patch sets by doing the following:

  • Writing new content for the new features.
  • Updating existing content for the updated features.

The BRM documentation package includes BRM core documents and BRM patch set documents. Detailed information about the new or updated features is directly added or updated in the BRM core documentation,  including concepts, procedures, opcode and storable class specifications, and online Help. A short summary of the feature is added in the BRM Patch Set Release Notes to make the changes for each patch set easier to find.

Along with a short feature summary, the BRM Patch Set Release Notes includes the description for the customer-reported issues that are fixed in the current release and the known problems in the BRM patch sets.

What Does the BRM Documentation Package Contain?

The BRM 7.4 documentation package includes 44 documents including seven HTML-only reference documents, a Patch Set Installation Guide, a Patch Set Release Notes, and Oracle Communications Pipeline Configuration Center documentation.

The BRM 7.5 documentation package includes 37 documents including six HTML-only reference documents, a Patch Set Installation Guide, and a Patch Set Release Notes.

How to Identify if a Document Was Updated in a Patch Set?

To identify the document updated for each patch set, the document part number is revised. This revised part number is used on the document title to identify the document revision. The Document Revision History table in the document’s Preface lists the history of the document revision and the changes made in the document for each patch set release. Typically, the information in the table contains a link to the new or updated section to help the customer go to that section; for example:

Document Revision History
The following table lists the revision history for this book.

Version

Date

Description

E16711-01

November 2011

Initial release.

E16711-02

May 2012

Documentation updates for BRM 7.5 Patch Set 1.

Minor formatting and text changes.

E16711-03

August 2012

Documentation updates for BRM 7.5 Patch Set 2.

Added documentation for the "load_brm_pricing" utility.

How Did the BRM Documentation Strategy Evolve?

The strategy of adding the detailed feature information into the core documentation and short feature summary in the BRM Patch Set Release Notes was first implemented in BRM 7.5 Patch Set 1. Readers can get all the information required to use the patch set features in one documentation set. This strategy has been used for all BRM 7.5 patch sets released.

This strategy was first introduced in BRM 7.4 Patch Set 17. Prior to that, new feature documentation was maintained in the BRM 7.4 Patch Set Release Notes.

Where Can You Access BRM Documentation?

BRM documents are available on the Oracle Technology Network (OTN) Web page and Oracle Software Delivery Cloud (OSDC) Web page.

You can download the documentation package from OSDC.

And you can also read online or download the docs from OTN:

What Are We Not Including in the Documentation Package on OTN?

Starting with BRM 7.5 Patch Set 4 and BRM 7.4 Patch Set 17, we are no longer posting the following HTML reference documents on OTN:

  • Opcode Flist Reference
  • Storable Class Reference
  • Event Notification Reference
  • PCM C++ API Reference
  • PCM Java API Reference
  • Customer Center SDK Java API Reference
  • Content SDK Java API Reference

If you need this reference material, you can download the documentation package from OSDC.

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:

Tuesday Apr 09, 2013

AIA Gets You There Faster!!

Accelerate your transformation and simplify cross-application business process integration using a standards-based, prebuilt integration solution to optimize business processes and deliver more compelling services faster.

Oracle Application Integration Architecture for Communications Overview Self Study Course Available!

I introduced Jodie Wilford, Oracle Communications OSS/AIA InfoDev Director, a few blogs ago when she wrote about updates to the OSS documentation set. In this blog, she talks about the Oracle Application Integration Architecture for Communications Overview course that's now available.

Cheryl Lander, Oracle Communications InfoDev Senior Director
 

Course Overview:
Oracle Application Integration Architecture for Communications (AIA) is a framework that helps you orchestrate business processes across enterprise applications.

AIA enables you to:

  • Build integration artifacts and flows that connect applications
  • Automate business functions or processes

For example, you can use AIA to improve the order capture and fulfillment process. The order capture process starts in a customer relationship management system and then proceeds to an order management system for further fulfillment.  You use AIA to build the interfaces and flows to automate, streamline, and improve the above process.

AIA provides the AIA Foundation Pack which consists of components that enable you to use SOA-based, pre-built integrations that productize business functions between applications.

Course Audience: The course is the starting point for anyone wanting to learn about AIA for Communications.

Course Objectives:

After completing this module, you should be able to:

  • Provide an overview of AIA for Communications
  • Explain briefly about the following AIA for Communications process integration packs:
    • Product Master Data Management (MDM) Process Integration Pack
    • Order to Cash Process Integration Pack
    • Agent Assisted Billing Care Process Integration Pack 
    • Revenue Accounting Integration

Course Duration: 30 minutes

Course Cost: $207 for customers

Customer Course Link

Oracle Internal Course Link

Course Creation: This was a collaborative effort with our AIA Product Manager, Navin Nair, and curriculum developer Raj Soni. The recording was done by Amanda Mills.  Thank you team for all the effort!

For more information on AIA.

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:

 


Tuesday Mar 19, 2013

Oracle Communications Network Charging and Control (NCC) 5.0.0 Overview Course Now Available!

Today’s blog is about the Oracle Communications Network Charging and Control (NCC) Overview Course that was recently released on the Oracle University iLearning site; Oracle internals and partners have access to this course at this time. I’d like to introduce one of our curriculum developers, Fraser Guthrie, who will tell you about this course.

Fraser has over 15 years telecommunications industry experience in a variety of cross functional roles, including software test, product management, consulting, support and training. He has about 7 years experience with the NCC product, including 4 years as a consultant with eServGlobal and Oracle implementing NCC solutions for communication service providers in Europe and beyond. Fraser has spent the last 3 years in the Information Development team developing courseware and training our customers, partners, and internal teams.

Cheers,
Cheryl Lander, Oracle Communications InfoDev Senior Director


What is NCC?

First, I’d like to talk about the NCC product. NCC is a session control and real-time charging product for intelligent networks. You use NCC to manage voice, data, and messaging services, and customized service offerings such as Friends and Family, Call Forwarding, and Favorite Destination. With NCC, you control and rate these services; NCC can control and charge for all types of network transactions, including traditional SS7 and newer IP-based services. Using NCC’s built in open Web 2.0 Framework, NCC can communicate with the Service Provider’s IT and back-office business systems, which allows you to integrate with Application Service Providers, provisioning systems, and to process EDRs offline. For customer billing and invoicing, you can integrate NCC with the Oracle Communications Billing and Revenue Management (BRM) product, Oracle’s convergent charging and billing platform, as well as other third-party vendor systems.

Who Is This Course For?

  • The NCC Overview Course is the ideal starting point for anyone that wants to learn about NCC, including (but not limited to):
  • Systems Administrators
  • Systems Integrators
  • Systems Architects
  • Sales and Pre-Sales Consultants
  • Project Managers

The course is the ideal starting point for anyone wishing to learn about NCC.

Course Content

The course introduces you to the NCC user interface. You will learn about the applications and main features of NCC and the underlying hardware and software architecture. You will also learn how NCC can be integrated into a communication service provider’s IT and core telecommunications network and how the product can be extended and customized. You will also see how NCC can be integrated with the Oracle Communications Billing and Revenue Management (BRM) product.

Lessons:

  1. Introduction to Oracle Communications Network Charging and Control (NCC)
  2. System Architecture
  3. Oracle Communications Prepaid Charging
  4. Oracle Communications Messaging Manager
  5. Oracle Communications Number Services Manager
  6. Oracle Communications Billing and Revenue Management (BRM) Integration

Course Duration: 2 hours and 12 minutes.

Course Link (Oracle internals)

Who Helped Me with the Course?

A special thanks goes to Brian Hudner, my colleague on the NCC team, who was instrumental in getting this course published. It is Brian’s lilting Irish brogue you will hear if you listen to the course. Brian worked on updating the courseware following Janet Taylor’s meticulous edits and then worked closely with Steve Snook and Barbara Stirling of Oracle University to get the course recorded. Thanks also to Jagdeep Kaur who worked on early versions of the course. Thanks also to NCC Product Management, engineering, and marketing for some of the source material and for reviewing the material as it was developed.

What Are We Working on Now?

Training material and courseware for NCC to BRM Integration and Voucher Management.

Where to Find Out More on NCC?

You can find out more about NCC by taking the course (of course!) and on the Oracle Web site

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
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
« April 2014
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
   
       
Today