Caylin Hirapara — Merce Project

Project Description

merceStudio is a fully customizable experience management solution giving large corporations the ability to build and manage their digital experiences for web, mobile, tablet and native environments. The editor allows companies to build out a digital experience quickly and easily. I have been working for PeakActivity as a copywriter since 2018, and I was commissioned to create all of the marketing material for the product, and more notably, I was given the task of writing, editing, and testing a user guide for the unfinished merceStudio product.

Here is a preview of the finished product:

merceStudio User Guide as a Webpage

Rhetorical Situation

merce is a new product being built by the technology company PeakActivty as an easy to use corporate ecommerce website builder, an all in one solution to creating a large company website that requires eCommerce sections to be the main focus. To understand the rhetorical situation of this product, it is important to understand the history of PeakActivity. PeakActivity is a small firm of that has become a leader in eCommerce replatforming in South Florida in the last 10 years.

Project Overview

Client: PeakActivity
Role: Technical Writer
Duration: Summer 2018 - Present

Tools

Markdown
Gifs
User Surveys
Audience Analysis
Persona
Google Drive
Sphnix
Gifs and Visuals

Competencies

Writing and editing skills
Visual communication theories and practices
Technological and media production literacies
Technological and media production literacies
Scholarship and empirical research design methods
Rhetorical theory

PeakActivity has particularly taken off for custom-built platforms for companies who use eCommerce technology in their stores for users and associates to complete purchases and find and test products in the store and online. Building a platform like this used to require separately developing product databases, mobile apps, desktop apps, point of sale apps, loyalty apps, multiple websites, and interfaces that didn’t necessarily communicate well with each other when it comes to updating and storing information. merce is trying to streamline that process.

After completing successfully these types of builds, the company decided to create a real solution to storing, updating, and creating all of the interfaces and applications required for these types of large scale projects. They hoped to solve many of the issues that they had found over the years in the process, such as having integrations with apps like Shopify and AWS and creating cloud-based databases that will keep sites running even if servers are down. In late 2019, merce launched the first beta platform. The first client site contained over 4,000 easily referenceable products.

In the midst of this, I had been working for PeakActivity as a copywriter in the summer of 2018, and 2019. I was tasked with creating all of the marketing material for the product, and more notably, I was given the task of writing, editing, and testing the user guide for the unfinished product.

Goals and Contraints

My goal was to create a comprehensive user guide specifically for the website-build and product database portion of the platform (merceStudio) for an audience of users who I determined to be non-technical marketing employees. They would be tasked with curating the website for their company. They will have to add and update content and products using the interface. With the launch of one client site just months away at the start of the project, I worked to create the user guide at the pace that the product was being built, with new parts and features being built each week and immediately added the user guide so that nothing was left behind.

I was constrained by the pace of the developers, and also my status as a remote worker. My own exploration of the product gave me most of my information, with support from developers and others. While I had plenty of time to complete the document, getting the necessary information was the hardest task.

Processes and Scholarship

Following the guidance of my reading, I guided this project with the 5 phase process model developed by JoAnn Hakos in the book Managing Your Documentation Products. The steps include the following:

Information Planning
Content Specification
Implementation
Production
Evaluation

Below is a plan of how I adapted these steps toward my project of creating a merceStudio user guide.

Phase 1: Information Planning

Phase 1 in Hackos’ (1994, 29–33) development model requires an initial investigation on the requirements of the documentation project and the estimation of resources required in the project. The required discussions to gather this information had already been completed by the client before I began work. They decided the plan as listed below.

Tools and Media

The authoring of the user guide will take place in GoogleDocs to allow for easy collaboration. Google Docs is the standard for documentation by PeakActivity and will allow for visuals including GIF animations.

The GIFs which will be used as visuals in the user guide will be created with Gyazo, a screen capture tool that allows the free export of .gif files. To gather the gifs, I found what seemed to be the hardest task to find and record the placement of the mouse and the process of completion. These were posted as .gif files onto the merce shared Google Drive. There they can be accessed and referenced when the time comes to post them onto the website.

The plan also included the creation of a series of videos created in Adobe Premiere Pro using screen captures and my own voice overs.

At the beginning of this project, I had agreed to host the user guide in

Audience Description

The following portion of phase one includes audience analysis. According to Hakos, this includes researching information on the users of the documentation and their goals and tasks in using the documentation.

There are two ways I chose to complete this. First, I analyzed the target audience for the product since the product boasts of easy website building for non-technical users. Second, I spoke with the product’s first-ever user to listen to her knowledge level and concerns about using the platform to better understand how to write for more people like her.

I was also able to use my knowledge of the merce platform for content strategy purposes to create two personas of the audience for the merce user guide. merce is marketed as an easy to use platform that requires little to no technical knowledge to upkeep. Based on my interview and my content strategy, I created two personas of the merce user guide user that would guide my writing of the user guide.

View the Full Audience Analysis

Timeline and Deliverables

In early July, the goal was set to launch the first company merce platform on November 1, 2019. This gave me plenty of time to create a user guide with all current launch features. Since the launch of the site meant that all parts of the site would be completed, the merceStudio user guide needed to be completed by October 1 to allow time for training and site migration. My deliverables to the company for this project included:

Project Plan for Client including Content Specification Plan
A literature review on the viability of gif animations as instructional tools
merceStudio User Guide Authored in Google Docs
merceStudio User Guide as a MarkDown File (For an easy transition to webpage)
Report on the usability of the user guide
Four 30-second videos demonstrating completion of common tasks
Project wrap-up report for the company

All deliverables were to be completed by Dec. 1, 2019.

Phase 2: Content Specification

Phase 2 in Hackos’ (33–34) development model involves adding details to the plans that have been compiled and approved for implementation in the previous phase. There were two deliverables in Phase 2: a content specification plan and a revised project plan. I compiled these into a single document entitled ““User Guide Plan and Content Specification.”” for submission to the client.

View the Full Project Plan and Content Specification

At this stage, I also completed a literature review on the viability of GIF animations as instructional tools. I took that information to decide to use gifs as the primary visual component in the user guide. My research uncovered a good amount of scholarship on the topic. Most notably were a variety of connected research studies on the use of animation in eduational settings. The conculusion of my research is that GIF animations can be used but only if certain guidelines are followed. When used correctly GIF animations are a great tool to aid learning. When used incorrectly, research shows that they can be a great distraction. I used these guidelines to move forward with my decision to use GIF animations as visuals in the merceStudio user guide.

View my full literature review of the use of GIF animations

Phase 3: Implementation

Phase 3 in Hackos’ (34–36) development model contains the design and the development of the documentation. This phase features several deliverables as multiple versions of the documentation. For merce, as agreed upon, this consisted of a user guide of existing documentation including GIF animations of current interface visuals.

Andrew Etter claims that writing is only 10% of the process of creating documentation. (Etter Ch. 4). I felt that it came together very quickly once I began writing. I closely followed Christopher Gales advice in “The Product is Docs”:

Write from primary sources. When writing procedures, perform a step and then write it immediately. Report it as it happens. There is a testing aspect to this, too: try making likely mistakes and seeing what happens. If the software does not handle errors gracefully, file defects. (106)

To write the user guide, I slowly worked directly through the merceStudio system. When I first began, there were only a few tasks that could be completed: Adding a webpage, editing a webpage, adding products to the page, and adjusting themes. I began with just those tasks, separating them by the tab in which they were contained in the system. Thankfully, the user experience in these tasks was good, and there were very few steps. But, as features and settings began to be added to the merceStudio, the functionality became more difficult to describe. Building upon what I started with, I kept the sections separated into the tabs in which they are found in merceStudio. Each week, the development team would present more new features, and I would document accordingly.

Near the end of November 2019, I had completed writing for what would become version 1 of the merceStudio User Guide. I was ready to present this user guide to the first client. While new features were constantly being added, the user guide remained up to date with the current features. I was also able to deliver four training videos to go with the user guide and to accompany the final user guide webpage.

View the merceStudio User Guide Video Library

It was decided that the first implementation would take place by way of a training presentation presented to the Operations Supervisor, who would oversee the implementation of merce for the first client. I prepared for this meeting by taking the user guide and dividing it into sections. I created a presentation where I would run through each of the simple tasks, for each section. In the background of my slides, I had planned to go through all of the steps in merce for the presentation while sharing my screen. Unfortunately, on the day of the presentation, I was informed that merceStudio would be down. Instead, I screen captured a long-form demo video which I was able to play on top of my slides to demonstrate the actions.

View the merceStudio Traning Slides

Phase 4: Production

Phase 4 in Hackos’ (36–37) development model includes the activities required to deliver the final version of the documentation to the user of the product. These activities preparing and localizing the final versions of the report into their forms. In my proposal I had assumed the final version of this document would be the Google Doc file and the Markdown file. I completed both versions in early December. I found a very simple Google Docs extension that automatically translated the doc to a Markdown file.

View the merceStudio User Guide As a Google Doc

View the merceStudio User Guide As MarkDown Files

But I found quickly that I was not going to be satisfied with the visual of the user guide if either form I had created. I wanted to generate a help portal like those I worked with on my Cengage project.

So as a part of this project, I decided I would take the opportunity to learn an authoring tool that had been introduced in my reading by Andrew Etter and my reading by Anne Gentle. A large part of both readings were dedicated to the idea that using Python with Sphinx, a static site generator, is the future of technical writing. Once I had my user guide completed to my satisfaction in Google Docs, I set out to learn how to translate it into a Sphinx generated static site as my readings suggested.

Several resources guided me as I learned. In the beginning, just the install of the Sphinx software was a challenge. Several Youtube videos guided me, most notably this one. Sphinx has a quick-start setting that put together a site for me in about a minute. While the file structure was confusing, I was able to find out through further research which files had to be edited to make the site. For example, all of the settings were included in the conf.py file, which was written in Python, but fairly easy to understand. I used several forums and articles, most notably this one, to adjust the settings. To create the site, I found that I had to open the “docs” file in the Terminal of my Mac, and tell the command prompt to “make html”. Once I did that, my site html was automatically written into the “build” folder.

My first step was to structure the table of contents in the Sphinx index file that it wrote for me. I wanted to structure the navigation so that it would fall into chunks that didn’t go below the fold of the page, and gave enough headings that users could click through to find what they were looking for. At this point, the card sort that I did for Cengage on their help portal navigation guided what I wanted the navigation to look like. I was aware from my readings on UX that I didn’t want to give users more than 7 options. I decided to break it up into the following categories:

Introduction
Managing Blogs
Managing Careers
Managing Products
Themes and Settings

I broke up my .rst files into these categories, and I placed these into the index files with the understanding that Sphinx would read the headings inside the files and make them into menu options.

While Sphinx boasts of it's easy use of .md files, I was unable to get the program to read my .md files that I had created with Google Docs. Instead, I had to translate them into reStructuredtext (.rst), another language I learned in this process. I found a converter that automatically created the .rst files from my MarkDown files. The converter also ran editing and spellcheck, which was very helpful at this stage. For Sphinx to read the files, I placed them into the “source” folder it had created for me and ran the “make html”.

I additionally took this opportunity to learn GitHub, another tool suggested by my readings. Github allows for cloud-based version control of my code. I was able to use Github, along with my Sublime Text Editor, to edit and keep my files backed up. I was also able to use the tool to share my files with my colleagues once the final version was complete.

After a few weeks of tweaking and editing, I finished the merce User Guide Help Portal. I was happy with the results.

View the merceStudio User Guide Help Portal

Here is a preview of the finished product:

View the merceStudio User Guide on Github

Phase 5: Evaluation

Phase 5 in Hackos’ (37) development model involves two activities: evaluating the current project and planning for the next version of the project. Hakos considers a major part of this phase to be a usability study on the document itself.

When I had first proposed this project, I determined a full-blown usability study with outside users to not be feasible with the current state of the product itself. But by the time the user guide was completed, I felt confident enough in the user guide and the product that I would be able to get quality results from a usability test. I performed a usability study on a small number of users who were not directly involved in the project for a think-aloud protocol usability test.

I set out the following tasks for my users to complete with clear instructions that they both find the location of the task in the help portal

Find the part in the help portal a section that tells you how to login in.
Using the help portal, log in to merceStudio.
Add a page and name it “Test”.
Add content to your page: one text block and an image content box to the page.
Separate them into two columns.
Preview how the page would look on a phone.
Delete your content.
Find where you would view product attributes.
Find where you would change the text colors.

I was pleasantly surprised by the ease at which my users were able to figure out the navigational structure of the user guide. I was also surprised by their ease of use of the system itself. Before I had even prompted them, all of my users commented on the usefulness of the GIF animations. The problems that users found were thankfully very fixable. Most problems involved misplaced images or text that was from outdated versions of the system. I was able to quickly fix these to make the user guide better. There were also some more overarching changes that will take some thought to fix.

merceStudio Technical Writing ProjectDocumentation • User Guides