skip to contentW3CSVG

Portfolio

Publish date: Dec 31, 2021
Last updated: Sep 28, 2023
1633 Words

This list starts from the latest thing I worked on. Where I have permission, I link to the docs that I helped create.

If you want to see some representative, larger-scale projects, I recommend looking at my work summaries for:

k6 and Grafana labs
Open source applications for mission-critical web infrastructure
Unit21
An enterprise web application, with an API and knowledge base
TrueBlocks
An open-source application, with a command line and API
ivelum
A web development company, with enterprise and open-source projects

There are a few projects that I had strong confidentiality agreements about. I don’t mention those. Everything else is in the open!

Rhize Manufacturing Data Hub

Time: September 2023–now

Description: A data hub to store data, execute workflows, and coordinate messages across a manufacturing operation.

Links: docs.rhize.com

Project: Leading the docs effort to communicate a novel software in industrial automation.

Tech involved: GraphQL, Go, MQTT, NATS, BPMN, JSONata

Authoring tools: Hugo

Docs as code: Implemented link checker, prose linter, glossary template, and various Hugo shortcodes

k6 and Grafana Labs

Time: March 2022–June 2023

Description:

Popular open-source tools for mission-critical internet infrastrucuture (observability and testing). k6 was a separate entity before Grafana Labs acquired it .

Both k6 and Grafana also have commercial cloud products.

Links: k6.io | Grafana Labs

Project:

I led the documentation work for k6, an open-source load testing tool with an embedded scripting engine. The quality of my work was publically recognized by users, and some longform posts were select by industry reviews as “best of the week”

Of course, good work is easy with a great team. The k6 team gave me a great content foundation to build on, and they provided as much time as I needed to ask questions and learn the product. I’m really grateful I could contribute to such a user-centered application and work with such talented people.

Work samples

Tutorials

  • Get started with k6. A four-part tutorial to learn how to use the k6 API and adopt a tests-as-code process.

Explanations

  • Load test types. Collection of conceptual material for beginners to load testing. Full rewrite that I collaborated on with the DevRel team.
  • Scenario concepts Technical explanations of how k6 schedules VUs. I wrote "Arrival rate" and "Dropped iterations" from scratch. The others were "deep rewrites."
  • The life cycle. Explaning the k6 runtime and scopes. Complete rewrite.

How-to guides

Information architecture

  • Grafana Cloud k6. Total migration of commercial docs, with information refactoring and re-writing. Throughout the docs, I tried to imbue industry knowledge to help new testers understand the reason to use the documented feature.
  • Results output. Reorganized page to provide easier entry to understanding and manipulating test results.

Longform


Besides my writing work, I also did some system administration and “glue” work: implementing linkcheckers, linters, and templates; attending customer calls; contributing to the community; and helping the Grafana docs team create templates, edit documentation, and implement a shortcode for admonitions.

Tech involved: Go, JavaScript, various cloud platforms to send and recieve data.

Authoring tools: Gatsby, Hugo, OpenAPI

Docs as code: Wrote reusable Gatsby components, Hugo shortcodes, CI flows for Linkinator and Vale, auto-generated glossaries.

ZITADEL

Time: February 2022–March 2022

Description: An open-source cloud application to help organizations implement their own auth.

Links: https://docs.zitadel.ch/

Project:

  • Top level edits of articles

  • Discussion and recommendations about overall information architecture

Tech involved: Go, Oauth, instructions for various frontend frameworks

Authoring tools: Docusaurus

Docs as code: Single-sourced content using MDX files.

Cascade Strategy

Time: October 2021–January 2022

Description: B2B app to help organizations plan strategies and integrate various systems into one single source of truth

Links: N/A

Project:

  • wrote a number of help articles about integrating the system with various third-party data sources.

  • Wrote a help-article template for others

  • Documented an entire REST API by studying the source code and using copy as cUrl in the developer console

Tech involved: PHP, JavaScript, SQL

Authoring tools: OpenAPI, Redoc

Docs as code:

Most of the docs-as-code for this project was for the API docs:

  • Extensive use of OpenAPI bundles to use the same source code for multiple versions of an API document (internal and external)
  • GitHub action to build and publish documentation
  • While the KB publishing system did not use docs-as-code, I did create a small template in Bash to standarize how I wrote the how-to topics.

Freelance Tutorials about Linux

Time: December 2020–February 2022

Description: private

Links: N/A

Project: private

Tech involved: Shell scripting, Linux

Authoring tools: Asciidoc

Docs as code: None

Design a REST API for a niche business

Time: November 2021

Description: private

Links: N/A

Project: Using the design-first approach, I created an API specification based on the users’ business needs. I could query the application’s database to see what data was available. The focus was on creating an API that was simple and useful. After I created the specification, the clients’ developers built the API.

Tech involved: SQL

Authoring tools: OpenAPI, Redoc

Docs as code: Schema reuse

Json-logic Scala

Time: October 2021

Description: A Scala library that serializes Scala structures into JSON, and evaluates abstract-sentence-tree expressions.

Links: https://www.jsonlogicscala.com/

Project: I reorganized the first drafts, improving clarity, flow, and overall information architecture. Gave advice on viable examples.

Tech involved: Scala, Java

Authoring tools: Jekyll, Github actions

Docs as code: Jekyll automatically organized the list pages for a collection of topics.

TrueBlocks

Time: April 2021–November 2021

Description: Local-first index and CLI for the Ethereum blockchain

Links: https://TrueBlocks.io

Project:

I won't lie: I have some misgivings about cryptocurrency in general. Yet, I am proud to have worked with TrueBlocks!

TrueBlocks is an open-source application that makes the entire blockchain locally searchable. It's useful not only for traders, but also for all types of investigation, including into scams and fraud.

A short summary of the work I did:

  • Built the documentation site and wrote all the install, how-to, and conceptual articles (see link)
  • Collaborated with the developer to auto-generate references for the command line and data structures.
  • Rewrote the REST API
  • Communicated with many users on Discord to test docs and to find places to improve documentation.

Tech involved: Go, C++, TypeScript, Linux, Shell scripting,

Authoring tools: Hugo, Redoc, OpenAPI

Docs as code:

This job involved extensive docs-as-code and automation. I used Hugo templates and variables to populate site data. Various shell scripts generated the reference docs from the codebase.

I used Github actions to deploy the site to a server, sync the code and docs repos, and check the site for broken links.

OpenLumi

Time: October 2021

Description: OpenWrt for Xiaomi Zigbee gateway with imx6 SoC DGNWG05LM, ZHWG11LM

Links: https://github.com/openlumi/openlumi.github.io

Project: Rewrote README to help users install a custom Linux OS on Android phones

Tech involved: OpenWRT, Linux, shell,

Authoring tools: Markdown

Docs as code: N/A

Unit21

Time: March 2021–September 2021

Description: Anti-money laundering web application

Links: https://docs.unit21.ai/ (some pages may be behind a login)

Project:

Unit21 gave me a lot of freedom to research solutions and create the docs in the way I thought was best. Their customer support team was great about giving me feedback and about delivering feedback from customers. So, we could constantly iterate and improve the docs.

It was very satisfying to see the docs “take life,” getting used by customers, customer support, and internal and external developers. With the success of the docs, Unit21 decided to hire a full-time technical writer.

A short summary of the work I did:

  • Built large knowledge base from scratch, documenting all major features, with tutorials, how-to guides, references, and explanations.
  • Rewrote the API using the OpenAPI specification
  • Interviewed many experts to add content
  • On-boarded incoming full-time technical writer

Tech involved: private

Authoring tools: OpenAPI (a.k.a Swagger), Readme.io

Docs as code: Used Github actions to automatically send files from a private repo to a public one. Wrote a shell script to generate a report from an internal doc.

B2B enterprise application

Time: November 2020-January 2021

Description: private

Links: N/A

Project:

  • Reorganized REST API
  • Wrote various infrastructure “playbooks”
  • Documented how major components of the code base worked, to help onboard new developers.

Tech involved: JavaScript, TypeScript, Kubernetes, Python

Authoring tools: OpenAPI

Docs as code: Autogenerated API documentation

Aspire Themes

Time: April 2020

Description: Set of themes for Ghost CMS

Links: https://aspirethemes.com/themes/krabi

Project: Rewrote and edited documentation to install and configure site. Note that the testimonial specifically mentions the helpful docs─twice!

Tech involved: JavaScript, CSS, Gulp

Authoring tools: Markdown

Docs as code: N/A

ivelum

Time: November 2018-present

Description: Web developers of large SaaS applications. Builders of Teamplify and DjangoQL.

Links:

Project:

I will always be grateful to the Ivelum developers, who trained me from scratch. This great team taught me everything I know about good communication, collaboration, and design.

Some things I’ve done for them:

  • edited internal and external technical texts
  • wrote build reports and updates
  • wrote various UX texts for the interface
  • Collaborated on blog posts and articles
  • Translated and updated the company wiki
  • Maintained the style guide for UX writing
  • Consulted on all aspects of written communication
  • Taught English─in many conversations, I’ve learned much about what matters to developers. Certainly the experience has helped me write for developer audiences.

Tech involved: Python (Django), JavaScript, Docker, React,

Authoring tools: Markdown, RST, MDX, Jinja2,

Docs as code: Used Jinja2 to template emails and UI. Used ternary operators in JSX to modify embedded instructions based on what the user selected.