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:

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