By chlander on Sep 15, 2014
This year we had our third batch of technical writing interns from Algonquin College in Ottawa, Canada on board for almost four months. Our goals for this internship program are simple: get some work done and give them insights into what working as a technical writer is all about. Once again this year I feel that we were successful on both counts. This year's interns Chris Ramey and Devin Roberts, worked on our Unified Communications Suite (UCS) documentation, helping us move some of the documents from a wiki format/publishing model into Structured FrameMaker and published on the Oracle Technology Network in an accessible format. They were able to do some re-architecting of content, editing, writing, and production tasks, so they experienced most of our doc life cycle processes. In addition to this blog, they did a Brown Bag session for the full InfoDev team, sharing their backgrounds, information about their school's technical writing program, and what they learned as interns. We appreciate their help and enjoyed having them on board. Here's to their successful career, hopefully as technical writers who will look back on their experience in Oracle Communications as beneficial and fun!
And now just a bit about these two interns: Devin and Chris are both former Arts graduates of the University of Ottawa. This background helped them to prepare for the technical writing field. After graduating from the University of Ottawa, they both attended Algonquin College’s Technical Writer post-graduate program to acquire the specialized skills required for careers as professional writers and came to Oracle for a four-month internship in May 2014.
Cheryl Lander, Oracle Communications InfoDev Senior Director
As aspiring technical writers, we were fortunate to spend the past four months at Oracle. The Technical Writer program at Algonquin College provided us with lots of theoretical background, skills, and writing practice before coming into a workplace. However, once we began working as interns here at Oracle, it was immediately clear to us that there are lots of things left to learn that the classroom just could not prepare us for.
We had the fortune of working with a team of senior writers on the Unified Communications Suite (UCS) documentation set. Many different products are incorporated into this suite, and there are several supporting pieces of documentation for each individual product. This blog provides a summary of the new skills and competencies we acquired while working on the UCS documentation project. For the most part, these new skills are not even things we anticipated learning.
Acquiring Product Knowledge
Knowledge of Oracle’s products is not something we could have learned in our Technical Writer college program. This is something that is learned on the job. We found that the best approach was to dive in head-first and get working on the documentation, while learning about the products along the way. Knowing that our internship would only last four months, we had to begin our writing tasks quickly so we could contribute to the documentation effort right away.
As we worked with the UCS team, we quickly realized that Oracle (and any other company we may work for down the road) has unique products and unique approaches to writing about these products. It became obvious that our challenge would be to learn and understand as much as we could about the UCS products within a small period of time. In addition, we also had to quickly adapt our writing style in accordance with Oracle style.
Working in a Dispersed Team
The UCS team that we worked with comprised writers living and working in various locations in the United States. Even though we came to work in our office here in Ottawa, Canada, we took direction from a team of senior writers whom we never met face to face.
This form of organization provided a unique work experience that neither of us had encountered before. Working in a geographically dispersed team presented several challenges that we had not anticipated. These challenges included:
- Working in different time zones. The writers on the UCS team are dispersed across three different time zones in North America. It required extra consideration when requesting a meeting or waiting on an email response as the working hours of other writers did not always coincide with our hours.
- Communicating effectively through email/messaging. Since it was not often convenient to speak to the other team members over the phone, much communication was achieved through email and instant messaging. This correspondence had to be carefully written to ensure effective communication. The topics of our discussions were highly technical and specific, so messages had to be written with precision.
- Organizing team calls. We took part in weekly conference calls with all of the members on the UCS team. It was important to schedule these calls on a weekly basis to ensure each team member had the same informational updates. We also had daily sync-up calls with individual UCS writers to help us along with our tasks. Both types of calls were essential in maintaining the direction of the UCS project.
This internship allowed us the opportunity to work collaboratively with other writers. Since the UCS team is dispersed across North America, we had the chance to learn about collaborative authoring techniques that allowed everyone on the team access to the same content. These collaborative authoring techniques included the use of:
- Wiki spaces. These were a valuable way to keep track of progress on various assigned tasks. Through these spaces, we were able to access task lists, product information, and level of effort spreadsheets to help keep us on track.
- Subversion (SVN) version control software. This was our first opportunity to use version control software. We were able to update the folders on our local hard drives daily to reflect the changes that had been made to documentation files by other writers. We also learned how to modify the documentation files through SVN.
- Beehive workspace. This online workspace allows files to be stored and shared by all teams working on a project. Specifically, we used this space to access writer and peer review checklists to use in reviewing documents.
Creating Documents According to Oracle Style
As new technical writers, we needed to get acquainted with the editing and formatting required to produce quality documentation. We reviewed, edited, and formatted documents that had been converted from an online wiki page into Structured FrameMaker. There were a number of things that needed to be done to ensure documentation quality, including (but not limited to):
- Ensuring that system commands cited in the documents were properly formatted
- Making the documents accessible to those with visual disabilities
- Editing the document to ensure it conformed to Oracle’s style guide
- Updating documentation sets for new releases
- Addressing comments made on the documents by software developers
Authoring Our Own Document
After working on Oracle’s UCS documentation set, we were given the opportunity to co-author a new System Administrator’s guide. This was the first time either of us had ever written a guide from scratch, so we were thrilled to have the chance to write our first one for Oracle. The guide tells system administrators how to use one of Oracle’s UCS products. It included instructions on how to initiate server functions by executing commands on a command-line interface. This was a fascinating guide for us to write, and challenged us to learn about a product we had no prior knowledge of.
We’ve had a fantastic experience working here at Oracle. We learned so such about technical writing over the past four months. This experience has provided us with knowledge that will be highly valuable in our future careers. Thank you to everyone who has made our time here so enjoyable!
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:
· Email firstname.lastname@example.org.
· Post a comment on this blog.
Thanks for reading!