- Writing and User Research
- Open-Source Projects
- Special Projects
- UX Text and Embedded Help
Writing and User Research
- Reorganize User and Admin Guides (Domino Data Lab).
Ran card sorts with Data Science Practitioners and System Admins to reorganize the documentation so they can quickly find answers. Click here for details.
- Sample Linux Installation Guide (ACI)
Deprecated example from a 130 page Linux installation guide typically used by Professional Services, but also provided to customers to install a complex software product.
- DITA samples (ACI)
Examples of help topics that I wrote for a framework solution.
- DITA samples (ACI)
Examples of a Concept topic and a Task topic that I wrote for a Fraud Prevention solution. End users are Risk Analysts.
- Command Line Interface Guide (ACI)
A redacted example guide for System Administrators and Rule Managers who had to provision and test a proprietary rules engine, as well as Risk Analysts who had to see how the data model and rules were set up in the engine. This guide described the data model, components, and commands for provisioning and testing the rules engine.
- Cloud Operations Guide
A redacted example guide for administrative and operational staff responsible for provisioning, configuring, managing, and operating a cloud-native solution when it is hosted in Kubernetes.
- Getting Started with Cloud – DRAFT
A redacted draft to show my familiarity with the cloud. This document was a work in progress.
- Workflow diagram (Contains confidential information) (ACI)
Created a user-friendly workflow diagram for end users with real world examples from a complex workflow, domain model, and UI activity diagram. The diagram will be used by the Director of Payment Risk Management and customer facing product people to help explain and sell the system.
- Embedded help (ACI)
Examples of embedded help that I wrote from a key framework product for the payments industry. End users are administrators or developers. See UX text and embedded help for more.
- Fraud Prevention System User Guide (ACI)
A PDF containing a short excerpt from a user guide that I wrote for Risk Analysts using a software solution for card-not-present fraud prevention and metrics.
- Web Service Implementation Guide (ReD)
A PDF containing a short, redacted excerpt from an implementation guide that I wrote for administrators and Solution Consultants to implement a Web Service.
- Mobile Device Management – iPhone (MFormation)
A PDF containing a short excerpt from a document that I wrote for enterprise administrators who must enable device management for iPhone iOS 4 devices.
- 2020 grammar challenges (ACI)
The ACI Information Development team received several weeks of grammar challenges. I thought would be an opportunity to share some of my writing skills.
- SDK Sample (ACI, password protected)
- ACI APIs
A link to a public pages that shows how users consume ACI APIs. I worked on APIs such as those for UPF’s Universal Transaction Repository. You must be a customer or employee to access the content.
- REST APIs
Presentation used to share knowledge that I learned after taking a course to teach other Information Developers about REST APIs and how to document them.
The Good Docs Project
Wrote a Release Notes template and guide to demonstrate best practices to developers, technical writers, and project owners to create excellent documentation. While working on this, I mentored a junior writer. See the release page.
Microservices, Containers, and Kubernetes presentation
Introduces basic concepts to the Information Development team at ACI.
Introduces relational database concepts to the Information Development team at ACI. I presented this with a demonstration. I self-taught myself SQL so that I could update the seed data (description text) in our framework’s user interface because developer’s didn’t have time to do it themselves.
Used to share knowledge that I learned after taking a course to teach other Information Developers about REST APIs and how to document them.
Information Development’s (ID) User Assistance Offerings
Used this to promote the ID team’s services. Encouraged other Information Developers to use this to evangelize our team’s services to their product teams as well.
I was asked to present to the Information Development team about accountability, using a recent case study. The goal was to motivate and empower the team, while giving them specific tools to use going forward.
Docs-as-code migration (ACI)
The previous link is to a blog post that I wrote describing this project.
Also, Create and manage content in IntelliJ is a document that was exported from Confluence with instructions that I wrote for internal users (Information Development, Product, and Engineering) to learn how to use our Docs-as-Code platform. I authored troubleshooting information too.
I led a team to create an onboarding program hosted on a Confluence to ramp up new hires. The goal was to move this to our Learning Management System in the future.
Click here for an excerpt.
Sensitive Word Analysis (ACI)
I led a team with two editors, a technical writer and a software engineer to further ACI’s goal to use inclusive language in its software and support.
We used the following process:
- Started with terms like blacklist, whitelist, master, and slave.
- I expanded the list of terms, using resources like Google and Microsoft.
- I researched standards being set by other major companies like GitHub, Google, Amazon, Ansible, Drupal, IBM, and more.
- The team categorized terms by race, hierarchy, groups, age, gender, and cognition.
- The software engineer mined product source files and created a report.
- The team categorized each word as: Industry standard, ACI entity, OK to change or Further research needed.
- We documented potential replacement terms. For example:
- (Customer) Class could be Category, Level
- Whitebox (testing) could be Clear box, Glass box
- Dummy value could be Placeholder value, Sample value
- See more here.
- We created rules like the following:
- “When “Master” appears in conjunction with “Recipient List”, drop the word “Master” so the result is “Recipient List”
- When the word “Master/MASTER” is followed by “Card” or “CARD”, or in context with VISA, do not replace.
- We created a presentation, shared it with our management, and he shared it with upper management.
- Delving into terminology considered to be sensitive in other cultures made the scope too broad.
- Replacing sensitive words is important, but relies on industry standards, which is referenced by our code and not easily separated.
- Updating product documentation is only a beginning. We need buy-in across the organization.
- Context matters. We created extensive rules during the analysis to demonstrate that the effort is not a find-and-replace activity.
My manager shared our recommendations with the Product organization in August 2020. As of September 2021, the Product and Communications teams chose not to pursue this other than including this in annual compliance training.
This was an excellent project, as it made me think about my own communications. We can never exercise our analytical skills too much. As writers, we research, analyze, and write. But, performing a large analysis presents other challenges that work very different parts of your brain. I lead a lot of teams, but this got us talking about topics that we had not previously broached.
HP OpenView Configuration Management (Novadigm/HP)
I created a DVD for HP employees to understand, use, and support the HP OpenView Configuration Management Solutions (formerly Radia). The DVD contained:
An overview of several HP OpenView Configuration Management Solutions products and information about essential processes.
readme (converted to a PDF for this site)
Two VMWare images and instructions about installing and configuring the HP OpenView Configuration Management Solution products.
Exercises that demonstrate the basic capabilities of the HP OpenView Configuration Management Solutions products.
A survey to determine the DVD’s effectiveness.
This was a special project with a sponsor and no assigned team members. I completed it successfully by reaching out to pre-sales engineers and Information Engineers with whom I had built a rapport throughout my career at HP. Teams in China assisted with testing.
UX Text and Embedded Help
UI reviews (ACI)
I reviewed every label for every page in ACI’s UPF [framework] system and others. The following is an example of a page whose labels I reviewed. I sent this back to the developers and product team, along with a description of my understanding about how the page worked.
I often had to push the team to “move us away from naming things the same as they were in the old software “just because that is what is familiar.” If it isn’t clear, then we should fix it. Older customers might have to transition, but it will make it easier for new customers if we make things more user friendly.”
After collaboration, the following is the final page.
Message reviews (ACI)
I reviewed messages in ACI’s UPF [framework] system and others. The following is an example interaction.
On every Management Action (such as Activate and Deactivate) performed, we will show a confirmation message toast as shown below. I was asked to suggest text for the following scenarios and a Title for the toast as well.
- Successful submission of command
- Problem occurred during submission of command (this would include any error during submission)
The success message must comply with the rest of the system.
- After verifying that the title can be removed, I recommended that we follow the established pattern:
Activate submitted successfully
Deactivate submitted successfully
- For an error, I asked how the user can fix the issue. Users can try again later because the process handling command was finished or unavailable. I recommended the following to comply with our established patterns and let the users know how to proceed:
Activate failed. Try again later.
Deactivate failed. Try again later.
Embedded help (ACI)
In ACI’s UPF [framework] system, on the Changesets page, the page help read as follows: “A changeset is a version.“
I learned that no one understood what a changeset was, so this is what the original writer included in the help.
After spending time with SMEs and asking the right questions, I wrote detailed online help. The page help was also updated as follows:
Changesets include the changes made to configurations, such as when you are onboarding institutions or merchants.
When a change is made to a configuration, the Universal Configurator automatically generates a changeset with a unique ID. The changeset record defines INSERT, UPDATE, or DELETE configuration changes that are pushed downstream into product-specific databases.
Use this page to find a changeset and review its details.
- UAT Script Template Gathered requirements, developed, and executed UAT scripts for Quality and Regulatory compliance systems at Musculoskeletal Transplant Foundation.