My job duties at Rapid7 are much different than they were at BigCommerce. While I still write documentation and help maintain API documentation, I find myself being able to help with training, processes and helping to make overarching decisions about documentation. Some of the work I am involved in includes:
- Creating metrics around the help documentation
- Writing product documentation. Some recent articles I have written (as of July 20, 2020):
- Advising on what an API and SDK MVP is
- What does a developer portal need to succeed
- Creating a plan to have open-source documentation for Metasploit.com
- Working with my teammates to close the content gap on tCell
- Researching and introduce new tools to make the documentation better
- Training my teammates on the more developer focused portions of our job
- Add tooling around our docs-as-code workflow
- For those not famaliar with the command line use GitHub desktop
- Create a branch with the ticket label and short description
- Work on your changes with frequent commits to save your work
- Make a final commit with a short summary of changes
- Push branch to documentation repo.
- In the pull request description - go into detail on any changes made with a link back to the original ticket.
- Add any labels needed
- Assign the PR to the reviewers for that week
- Setup codeowners to make sure all PRs were reviewed by someone on the docs team before publishing
- No one can publish to master. Not even the codeowners
- To filter out all the spam by being codeowners, integrated GitHub into a dedicated Slack channel and setup keywords so we could know when we were tagged as a reviewer or a review was re-requested
- Create a Gmail filter to remove the “noise” since we have Slack notifications
- Add in GitHub actions for Vale, First time committers and link checkers
- Only create branches from master
- Start every day by pulling from master
- We don’t care about the commit history
- No need to squash. IF you want to squash use the button in the GitHub Repo, don’t do it locally (its confusing locally)
- Leading weekly sessions on making the most of the new tools and figure out the process
- Converting the style guide to Vale
- Added plugins to help check for broken links and format the markdown
- Convert the InsightIDR reference documentation from Markdown to OpenAPI 3.0
Metasploit Pro is the first project I tackled. Read More
The documentation needed an audit for gaps and a new site Information Architecture. I started by interviewing support, the engineering team that manages the product, and the previous writer. All of the information allowed me to create a plan to organize the site by a standard pen-testing workflow, along with user interface walkthroughs. I also organized the information by importance to the customer.
Metasploit Framework open-source
Metasploit Framework is an open-source tool managed by Rapid7. The challenge with Metasploit Framework is that it needs documentation, and the documentation should be community-sourced. Read More
To help the community begin to self manage, I created a process around adding documentation to Metasploit Framework.
There is a project on the repository where anytime a new feature is added, a card must be added. The card will include information about the feature and what should be documented.
I also wrote new contributing guidelines. They include a style guide, content examples, and tooling around the process. To help the community write documentation without me standing over them, I used a Vale https://github.com/errata-ai/vale, to convert the style into .yml files they can check the writing. I also recommend they install Markdown lint, https://github.com/DavidAnson/markdownlint, which verifies that the markdown is written in a consistent style.
I am tasked with creating training around the more developer focused parts my job. Read More
The first significant piece of training was a crash course around documenting APIs.The team needed to get up to speed and quickly. I used Stoplight https://stoplight.io/as the basis for the course because it provides a simple user interface you can use to compare to the Swagger.
The class is built using Hugo and Netlify. https://github.com/tjperry07/ux-writing-training
At BigCommerce I was tasked with doing a full revamp of the BigCommerce developer site. This included rewriting all existing documentation, creating new spec files ,and finding a system that would work for both writers and the company. This meant working across the company with engineering, support ,and our developer advocate to create the best possible experience. As of May 31, 2020, that foundation is still in place.
Some of the work that I completed included:
- Rewrite of all developer documentation
- Creating new content to get the documentation up to date
- Rewriting API spec files
- Creating missing spec files
- Create site information architecture
- Figure out if the company should build a solution or go with a SaaS solution
- Writing and testing code for the documentation
- Verifying the accuracy of specification files
I have included several writing samples and specification files.
Widgets writing sample
A new feature was released that required an overview article, tutorial, code samples and a new API to be documented. Read More
BigCommerce released a new feature that would allow developers to make reuseable “blocks.” Customers could then add text or images to the “blocks,” making the stores easily customizable. The release required a lot of documentation to work in step with each other and strong collaboration with the project manager and engineering. The documentation included an API that needed to be checked for accuracy, a tutorial, code samples, and a full overview to explain the unfamiliar terms introduced.
One of my first tasks, when I started, was to update the specification files. Read More
My tasks included creating a style guide, adding samples, and making sure the information was accurate. I also found many APIs that were not documented and needed to be made public. I used a Stoplight to create the files and make the maintenance much easier for my self and others who wanted to edit the files. They were not built from code, so they needed to be handwritten. I created a style guide, worked with the engineering team, and created a system, so the specification files were kept up to date. The biggest project I completed was the Catalog.yml file. It required months of work and collaboration to make sure all the information was correctly documented. I created close to 15 spec files. I have linked to a few that set the tone for the API style guide.
Other writing samples
These writing samples are a mixture of reference materials, tutorials, postman collections and concept articles. Read More
Developers Guide to Headless Commerce - This is a mixture of marketing and developer documentation. It is meant to inform and get the developers excited about headless commerce. The guide also includes several Postman collections meant to guide the user through a standard workflow.
Webhooks - Webhooks used to have a lot of confusion around them, and they were not well documented. I add some information on which events are available and created a quick tutorial based on an app our Developer Advocate had written.
Working with Storefront APIs - I noticed a gap in the content around how the Storefront APIs. Developers needed to know what they were and how to use them. This article is one of the earliest I wrote, and it's always a treat for me to compare this to the Widgets documentation that I wrote much later. I can see how far I have come.