Publications Planning (“Pubs”)

Context

I joined the Technical Writing (TW) team at Mavens, a Komodo Health (“Komodo”) company, in December 2021, when Publications Planning (“Pubs”) was still in the midst of development. Pubs is Mavens’s Salesforce solution for helping publication teams manage their scientific articles, including drafting and reviewing the content and budgeting and coordinating their submissions to congresses and journals. In the summer of 2025, Pubs was renamed to Scientific Publications Cloud (SPC).

Within my first few months of joining Mavens and Komodo, the opportunity arose to create a Pubs user guide for one of our first and biggest customers. Though the TW team had traditionally only delivered release notes and administrative guides on the public documentation site for Mavens’s Salesforce products, we all agreed that this project would be a great way for our team to both increase our exposure within Komodo and expand the type of work that we could do. When my manager informed us about the project, then, I immediately volunteered to take on the work.

Writing Process

Once I stepped up to create the Pubs user guide, I was invited to several meetings to help me better understand the project objective, the key stakeholders, and the product itself. I spent most of the first two weeks attending training sessions, completing the accompanying assignments, and drafting out an initial version of the user guide. The training materials were very crucial to my delivery of the user guide because Pubs was not yet a live product at the time and there was little to no documentation on the product otherwise.

Information Architecture

Aside from the speed at which I had to learn the product, Salesforce as a platform, and the overall process of how scientific content is ideated, written, and published, deciding the information architecture for the user guide was the most challenging part of this project.

I was primarily conflicted on whether I should organize the content based on the product’s features or on the users’ tasks. The training sessions that I was attending – and that the clients themselves would receive – presented the product according to the step-by-step tasks that users needed to complete throughout the publication planning process. However, even though the structure of the training sessions made a lot of sense, I was hesitant on producing a user guide that would contain redundant information.

With this concern in mind, I started my first draft with a feature-based approach, using the main components and entities of the product as the main section titles.

A sample of the information architecture of my first draft.

Yet, the more I wrote, the more I felt that the organization of my draft did not flow well. I was mixing explanations on how to navigate and use core Salesforce elements and Pubs components with instructions on how to complete certain tasks. Additionally, because a large portion of the publication planning process in Pubs relates to the annual plan that organizes the client’s budget and body of work for a single year, a section completely dedicated to annual plans would become very lengthy very quickly. The section would also be confusing to users because it would assume some prior knowledge about other components in the product. For example, I had created a section under “Annual Plans” called “Create a new line item,” which gave instructions on how to attach a line item to a manuscript. However, I defined and described manuscripts in another section under “Documents” called “Types & Subtypes.” The information architecture of my first draft was therefore contradictory because it assumed that users would both read every single section in order, which users rarely do with reference materials like user guides, as well as skip through the sections to find specific information. I knew I needed to quickly re-evaluate my organization of the content.

Some issues I found with the information architecture of my first draft.

I decided to create an entirely new draft with a task-based approach, focusing on the work that users needed to complete to write and publish a scientific article instead of on the disparate features in the product. I then consulted my manager, a former technical writer herself, to review both drafts and give me some feedback on which approach made more sense. We both agreed that the latter task-based approach seemed better given the user flow of things, so I continued working on my new draft. I was heavily relying on the training sessions to organize my content as I had initially feared, but I knew I had a reason for the approach I was taking.

As I worked my way through all of the training sessions, though, I still ended up creating a “Pubs Framework” section in the beginning of the user guide to introduce the major Pubs components that were frequently reused or referenced. This way, users could first learn about the core components in the product and then reference specific sections of the user guide to complete their individualized tasks. Ultimately, then, I decided on an information architecture that incorporated both a feature-based and task-based approach with an emphasis on the latter.

A sample of the information architecture of my final draft. The “Basic Navigation” section is discussed below.

Word Choice

As I was drafting the user guide, the Director of Quality, one of the key stakeholders of the project, occasionally came into my document as both a subject matter expert (SME) and a peer reviewer to provide feedback on what I had written. I accepted most of her feedback, but also pushed back on others, such as those on diction.

For one, when she suggested I replace the phrase “Please reference [table/figure/section]” to “See [table/figure/section]”, I advocated against using “See” because it could be ableist or potentially ableist. She agreed to keep my original word choice.

Additionally, because Pubs is built on top of Salesforce, she wanted to ensure that I was not using terminology that was too technical or that may have a different meaning for the users (e.g., “widgets”). Likewise, I wanted to ensure that I was not assuming any Salesforce knowledge of the users (e.g., “highlights panel”). I worked with her to finalize which Salesforce entities I was referring to as “tabs”, “subtabs”, “components”, and “sections” and ended up creating another section in the user guide titled “Basic Navigation” to explain some of the Salesforce entities.

An annotated screenshot I included in the final user guide explaining the different types of tabs in the Salesforce-based product.

An annotated screenshot I included in the final user guide explaining the different sections and entities in the Salesforce-based product.

Review Process

The internal stakeholders frequently reviewed and commented on my drafts at the same time that I was writing. Aside from the examples mentioned above about specific word changes I was asked to make, there were also several instances where I needed to insert additional sections on content that was not mentioned in any of the training sessions. For those, I simply had to ask the SMEs to walk me through the user flows in the product to craft the new sections. With these additions, I felt even more assured that my user guide would supplement, rather than duplicate, the training sessions.

Final Thoughts

I am very grateful to have had the opportunity to create an exhaustive user guide for a big client. I am especially grateful to my manager and teammates who agreed to let me take on this project even while knowing that I was new to the company, the team, the role, and the product. Through this opportunity, I learned the importance of having a rationale for each word, sentence, paragraph, and section that I write; technical writing is a user-focused craft, and if you can’t explain your reasoning to fellow teammates and stakeholders, you can’t be sure your audience will understand the content you deliver either.

Upon submitting the user guide, I was complimented by the Director of Quality in our company-wide peer bonus Slack channel. This project was both challenging and rewarding, and I look forward to more opportunities like it.