My Role at IBM

As a Technical Writer on the IBM Cloud Content team, I delivered the content experience for Cloud Security products new feature releases, reviewed and updated existing content, and heavily contributed to the API docs-as-code framework operations.

The content experience that I produced covered a variety of formats as applicable to each release:

• Product Guide
• API docs
• CLI, SDK, and Terraform docs
• Client Announcements
• Release Notes
• UI/UX review
• UI content strings
• Blogs
• Other ad-hoc marketing support 

Unfortunately, given the proprietary or internal aspect of a lot of the content that I created, and the fact that the UI is behind a paywall, I’m limited in what I can include in this portfolio from my time at IBM.

The Challenge

Watson Machine Learning provides a full range of tools and services so that you can build, train, and deploy Machine Learning models. A key responsibility for the focal in charge of setting up the Watson environment is to configure the compliance posture to keep the SaaS resources within the environment secure. To do so, IBM Cloud Security and Compliance Center developed a feature to scan Watson Machine Learning services in an IBM Cloud account. 

The deliverables of the content experience that I produced for this release included a tutorial, UI review and new strings, error messages, API / CLI strings, and Release Notes. The tutorial is featured in this portfolio.

The Solution

I decide on the deliverable types depending on the level of complexity of the release. Some releases, like a new button or a new option for an existing field, require simpler updates. A Focal who needs to secure his Watson Machine Learning with Security and Compliance Center also needs to access their organization’s instances of IBM Cloud Secrets Manager. 

The process to secure Watson Machine Learning resources was best documented through a tutorial. A tutorial is a specific content type with specific guidelines from the IBM Content Framework team. It’s best used to document the completion of a goal from beginning to end, with many moving pieces, instead of simply documenting the steps of a single task. 

Research and Collaboration

A solid foundation for understanding the technology behind this release was my recent completion of the IBM watsonx.ai Technical Essentials badge through which I gained an effective understanding of the IBM watsonx platform, the foundation models, and generative AI as well as learned to construct effective prompts in the Prompt Lab.

As usual, I identified and interviewed my project points of contact such as the engineers on the dev team, the architect, the designer, the Program Manager, and other subject matter experts (SMEs). I generally prefer to approach the SMEs after carefully reviewing the planning documents and other written material in the release’s repository.

I also reviewed the existing relevant docs pages of the services that are associated with the release. This way, I could ask questions with enough context that I could gain a fuller grasp of the task at hand and minimize the amount of potential follow-up meetings. 

Having studied the communication styles of my various team members, I’d adjust my questions and approach as needed, such as possibly needing to record the interview for later access, or sending notes, questions, and drafts ahead of the meeting.

Working in an enterprise setting for years, it quickly became clear that effective and harmonious collaboration was the key to organizational success. On my teams, I like to put my hard skills to use on solving my teammates’ content relevant problems, to provide a solid and authentic basis for our soft skill interactions. Dedication to competence is my collaboration language. 

Writing

The IBM Cloud Platform content team maintains an expansive set of content guidelines that each Technical Writer must follow. The content production process involves the use of Acrolinx, a content tool to scan technical communication for compliance with the organization’s brand, tone, terminology, and SEO guidelines. 

I coded the docs in Markdown by using Visual Studio Code. I used the command line, GitHub, and GitHub Desktop for docs ops. I used Postman for testing API docs as well as the command line. As part of my Masters program, I studied and coded documentation in DITA by using Oxygen. 

Clarity, a conversational tone, and a strong technological conceptual basis were at the forefront of this tutorial’s writing process. My drafts were reviewed by peers and SMEs, and I presented the content experience at various stages of completion at weekly playbacks for feedback. 

Design 

The designer assigned to the release usually sends the UI mockups for my review in Figma. Together, we discuss what strings are needed for each frame, emphasizing conciseness, especially given UI space limitations. After updating the mockups and clearing approval, I’d then update the strings directly within the staging environment for further review. 

Although not necessary for this release, I’d often create technical diagrams in Adobe Illustrator and Figma to be featured in the docs. Presenting information visually is a key aspect of effective technical communication, therefore multimedia content production is a core focus of my work.  I used Camtasia for video editing at Nokia, GarageBand and Logic Pro for audio projects. 

Final Thoughts

With each new release, I deepened my technological grasp of Cloud ecosystems. Whether through deep research of existing docs, online courses, SME interviews and collaborations, and designing visual representations of what I’m learning, my time at IBM extensively helped me expand my enterprise design thinking. 

A Technical Writer’s toolbox requires the ability to quickly understand complex topics through advanced research skills and practices that she can transfer from one environment and objective to the next. So not only did my time at Nokia and IBM teach me specifics about Cloud technology, automation, and DevOps, I can lean on my deep knowledge of these technologies to analyze other technologies based on similarities, differences, interactions, and abstractify as needed to grasp the overall logic and underlying theory of what I’m documenting. 

As soon as I understand the logic, I can:

1. Match it to the mental model of the users
2. Identify what to emphasize and relate to others in order to prioritize their needs and goals as well as maximize the utility of the feature
3. Brainstorm how to anticipate errors and provide recovery guidance
4. Select how to express relevant limitations and instruct workarounds

I decided to build a career in Technical Communication because I’m passionate about solving complex problems. I look at chaos and I see patterns. I use my tools to make them emerge on the page, on the web, on film, on audio waves, on the canvas, or in simple conversations. And at this stage of my career, the best roles for me to bloom are where I can put my complete toolbox to use to solve problems that help make the world a safer place. 

---