Technical Writer at Cornell
In my portfolio project, I will be sharing my experiences and the project I worked on as a technical writer and analyst for Cornell’s IT department - specifically the Academic & Support Services team. There, I worked with another intern to prepare and revise documentation for various audiences ranging from IT to faculty and students.
Role: Technical Writer / Analyst
Tools: Drupal, TDX, Excel, Cornell style guide
Duration: 3 months
Project Goals
The goals of the project were to update documentation, specifically knowledge base articles, on TDX and IT@Cornell to,
-
Reduce backlogged ticket requests and bottlenecks in support.
-
Improve service automation to reduce maintenance requirements.
-
Empower users to use documentation, references, and/or automation instead of using support resources.
Overview
For the 3 month internship, I worked alongside my manager, supervisor, and fellow intern with the responsibility of adding and improving 30+ knowledge base articles for the TDX and IT@Cornell platforms.
Role
For my role I held responsibilities such as:
-
Creating an Excel spreadsheet to audit all of the TDX documentation to give suggestions on possible improvements, monitor our editing progress, categorize their placements, and more.
-
Revising knowledge base articles by utilizing Cornell's style guide.
-
Improving accuracy of information in the documentation by talking to subject matter experts, manager, and supervisor for feedback then implementing those changes.
In my position, I worked alongside another intern who worked primarily on the IT@Cornell side. Towards the end of the internship, I began working on both platforms. During this point, I began writing for those who aren’t as technical and would prefer straightforward and brief instructions or information.
A snippet of the audit I conducted and organized in Excel
ADI Project
Editing and Proofreading Processes
To revise TDX and IT@Cornell knowledge base articles, I drafted rewrites and asked for feedback once I finalized the drafts on Drupal or TDX’s CMS. I followed Cornell's style guide to ensure consistency throughout. Here are examples of how I marked up the documents using Google Docs along with the before's and after's.
Example 1 - TDX Article Revision
For this TDX article it discusses how technicians can assign specific tickets to other technicians in TeamDynamix. The article needed changes as there were issues with wordiness. To fix these issues, I added headings to break up the various contexts and include important information upfront instead of in blocks of text. See the original text for additional context on how hard the text was to read at first.
Before
To make my edits, I used Google Docs to help me revise the wording, grammar and so on by marking them up in red and crossing them out. This was a method I learned in technical editing so I can save my edits in case if the CMS's failed.
After
Revisions:
-
Changed the title to comply with Cornell's style guide and to make it more representative of the text.
-
Added headings and subheadings to break up the large chunks of text.
-
Shortened lengthy text from the original article.
Example 2 - IT@Cornell Knowledge Base Article
The purpose of this article is to give users instructions on why updating memberships is important and how to do so. To structure the article to be appropriate for those not well versed in technical jargon, I made the tone and diction understandable and increased the brevity of the information.
Before
After
Revisions:
-
Added the 'Adding Group Members' and 'Removing Group Members' since they weren't originally in the document. The suggestion brought by my manager helped fuel this idea.​
​
-
Simplified the wording to be straightforward considering the article is like an instruction guide and the user wants to find their answers quickly.
​
-
Moved important points to the beginning of corresponding sections as 'Notes' so the user can know this information upfront.
Purple edits highlight the suggestions my manager gave me when I asked for feedback. In the additional drafts below, I used this method a few times when I needed help from a subject matter expert on the team or team in the same department as Academic & Support Services.
Example 3 - IT@Cornell Knowledge Base Article
For another IT@Cornell article, I updated the contents to include Outlook's newer settings for adding safe emails from being routed to junk. Furthermore, with the purpose of the article being to prevent TDX emails from being put in junk email, I made sure the steps and information were straightforward and easy to skim.
Before
After
Revisions:
-
Updated steps to match current Outlook settings.
​
-
Removed the images for being outdated and the steps seem simple enough to not need images and comply with Cornell's style guide.
​​
-
Edited the title to not have "how to" and comply with Cornell's style guide as well.​
While proofreading the document, I noticed the Outlook procedures were quite outdated as well as the images. Cornell advises not using many images (if possible) along with steps as the system changes frequently, so I revised only the steps. To do this, I rewrote the steps myself by figuring out how to reroute emails in Outlook.
To further elaborate my editing processes, here are all of my rough draft edits of 30+ knowledge base articles. The TDX articles are for the backend, so I do not have access to my final drafts but still have the edits I made. Warning, it's a lot!
Presentation and Publication
For the final presentation, I prepared an executive summary for the executive leaders of the ADI program explaining my summer project, my experience working on the team, what I learned, and feedback on the program. Though the presentation was remote, I used that time to elaborate what I liked about the program and what I wish I could've learned more about such as API documentation and administrator roles.
Retrospective
Working as a technical writer and analyst for Cornell was a rewarding experience and practically solidified my eagerness to work in the field. Additionally, there were some experiences I benefited from like,
-
Gaining understanding of IT infrastructure and TDX systems.
-
Editing documentation for the benefit of many students, faculty, and staff.
-
Improving CIT’s service automation by refining documentation.
​
On the other hand, there were a few constraints I had such as:
-
Little time to understand the systems.
-
Team was not as big so difficulty with getting certain information to write for articles.
-
Cornell style guidelines were confusing at times yet contradictory to my previous learnings.
​
That being said, the program allowed me to improve my skills and apply it in a setting where others will benefit from the revisions and improve automation for the department.
​
