Passionate, and occasionally pedantic, writer with a penchant for puns!
UX and Technical Writer
I love translating complicated technical language into something users can understand. I love learning about what our software and products can do for our customers, and helping our customers use it. I love the challenge of taking longer sentences and breaking them down into something far more manageable to read. When I describe my job, I tell people what I do is precision writing. And I'm awesome at it.
Help text inside the software
For the help text I wrote inside the software, I kept it short in order to avoid reader fatigue. I want users to be able quickly locate what they need to know, and not get lost in verbiage.
I used paragraphs in help text to this end as well. Many paragraphs were only a sentence or two long, as breaking up individual points with a new paragraph makes that information easier to parse. It also makes it less likely the user will stop reading.
Some examples of my help text include:
What is a document category?
A document category is used to organize documents by area of focus. The document will appear in a folder for any category with which it is associated, and multiple categories can be used for a single document.
Document categories are defined in list management; only categories for training will appear for selection.
How can security classifications limit access to documents?
By default, document security is controlled by the explicit user permissions needed to access documents of each type. Any security classifications are ignored and hidden when uploading or accessing files.
If desired, document security may be further limited through security classifications that require users to have additional permissions in order to view documents. Use of security classifications, which are associated with uploaded files, may optionally be required for documents or may be required for all documents.
If security classifications are required on all documents, at least one security classification must be identified to associate with all documents uploaded through the portal.
Error messages
Error messages should focus on things that the user needs to know. Which end is the error on, ours or the theirs? How will the error affect the user? And, is the error code truly necessary for the user to see?
Another focus on error messages was to provide clear language, instead of language that hedges information from the customer. An error message I received a request for initially read:
The connection may be down
The connection to the API appears to be down. If this does not resolve itself, please reach out to the help desk.
This kind of language is problematic, as we know the connection is down, because the user wouldn't be receiving this message otherwise. Additionally, the request to "reach out" was not what we were using for our "voice" in the software. I reworked the error message to be more clear, matter of fact, and in keeping with the software voice.
The connection is down
The connection to the API is down. If this does not resolve itself, please contact the help desk.
Additionally, another error message needed to be created in order to make it clear who the user needed to contact, as we were able to identify if the error was on our end (the help desk), or on the API's end. In this instance, I created a new, second error to make it clear where the error was coming from, and who the user needed to contact in order to resolve the error. Creating this second error message would not only prevent our help desk from receiving calls they would not be able to resolve, but it would prevent the users a lot of frustration from being told to contact one source, only to be told to call a second number to resolve their issue.
There was an issue reaching the API
There was an issue communicating with the third-party API. If this does not resolve itself, please contact the API administrator.
Validation errors
Validation errors are in-software messages that would point the user to an error in text input that could be corrected immediately. These messages did not appear in pop-up modals, and had slightly different patterns. While they did not have titles, I tried to keep them shorter than standard error messages just due to the fact that they would appear in the software.
In one instance, I did change one of the text patterns in order to give the user better information. On a range validation error, the original pattern was to simply give an error for out of bounds on the lower range, and a second error for out of bounds on the upper range, which could sometimes result in two separate validation messages. I combined those so any range error would give the user the full range, and only one validation message would be returned.
The number of days for the reminder schedule is not valid. Please enter a number between 1 and 99.
Collaboration with software developers
I believe that all writing can be improved by editing. While it is necessary to write quickly and finish text, I find that when possible, writing is always improved when it can be done with at least one other person editing. I enjoy working on teams, and find that every person I have worked with has made me a better writer.
Part of collaborative writing has always been about asking questions, rather than insisting on conventions. Frequently, collaborative writing isn’t a formal process. For the following example, our devs reuse text when available, and in this instance, a new API was being added. However, the previous APIs provided specifics on configuration errors if the url or login information was incorrect. For the new API, the devs discovered that these errors were not separated out, and those two errors needed to be combined into a single error.
The API cannot be reached
The URL provided for the API is not valid. Please enter a valid URL.
The API cannot be reached
The login credentials provided for the API are not valid. Please enter valid login credentials.
The dev pair working on this contacted me with the issue and their solution, which was to keep the title, and use “There was an issue with the configuration of the API client. Please ensure the URL and login credentials are valid.”
While that text isn’t necessarily bad, they contacted me because, in their words, they were concerned that the word ensure might make users think about a drink for senior citizens, rather than the issue. Even more important from my point of view was the fact that the two error messages were older messages, and we had moved away from using login to using sign-in instead.
A quick Teams discussion allowed me to craft a better message, fix the older messages, and validate the devs decision to come to me with questions about this text.
The API cannot be reached
There was an issue with the configuration of the API client. Please confirm that the URL and sign-in credentials are valid.
Technical writing
The release notes writing process involved a group effort of not just myself, but QA to provide screenshots and initial explanation of the feature, as well as two additional team members as editors. The release notes involved a introductory statement explaining what had changed, and the value the change had for the customer, and then included step-by-step instructions on how to use the new features introduced in that release, along with screenshots. For confidentiality reasons, the screenshots are not included in the following writing sample.
Create a Bank of Screening Questions
Acadis Recruiting has been updated, providing users with access to the list of screening questions page, and the ability to use the view link to navigate to the screening question record page. The Add a Screening Question modal has been updated, allowing users to add reusable Text, Checkbox, Dropdown, and Likert Rating questions to the list of screening questions. All questions from existing screenings have been migrated to a new screening questions bank as separate records. This will provide recruiters with a centralized location to view and manage their inventory of screening questions added to Acadis.
In Admin, on the Role Record, under Recruiting, a new Screenings – Questions business function is available for managing Screening-related questions. With the permission to edit Roles, the user selects the corresponding Read and Edit check boxes before selecting Save, which will allow the role assignees to view, add, and/or edit Screening questions. For this demonstration, Delete is left unchecked to prevent the assignees from deleting those questions.
In Recruiting, from both the Screenings left menu and splashboard tile, both the List Questions link will display for users who can read Screenings – Questions, as well as the Add Question link for those with the ability to edit the questions. Select Add Question to create one or more questions for screening purposes.
In the Add a Screening Question dialog box, the Owner, Question Type, and Question Text fields are required, regardless of the type of question. To proceed, select the owning academy in the Owner list.
The Question Type list contains the four types of questions that apply to a screening. Select Checkbox in the Question Type list as shown below.
For this Checkbox question, enter the information shown in the Question Text, Checkbox Text, and Help Text fields below, and then select Save & Add Another.
With Text Question selected as the Question Type, Field Input Size options display, one that will allow a single-line response, and the other that will allow the entry of multiple lines of data. For this Text Question, select Provide a text box for multiple lines for data entry, then Inactive in the Status list, and select Save.
The user is notified that four new questions were created via the new Screening Questions page. This sortable list contains all questions regardless of status, and indicates which are currently in use by an existing Acadis Screening. Additionally, the standard controls are available for printing the questions and/or customizing the displayed columns, as well as to navigate to a different page via the “Go to” link.
As illustrated below, selecting the Question ID header re-sorts the question bank according to ID, effectively showing newly added questions at the top of the list. The Add Question button will also display at the bottom of the page for authorized users. Select 10056 under Question ID to view the “Length of Military Service” dropdown question.
Question 10056 displays the related details, including each designated Dropdown option, as well as the Requirement setting, showing this question is designed to require a response. Furthermore, as a newly added question, the assigned Version number indicates this is the original record. With the permission to edit Screenings – Questions, the user selects Edit.
In Edit mode, the specified Owner and Question Type cannot be changed regardless of the type of question. The remaining fields may be updated, which for a Dropdown question, is Question Text, Dropdown List, Requirement, Help Text, and Status. To demonstrate, the user selects the Requirement check box, and then Save.