Microblog

Last week, I was updating a doc and realized we have two very similar-sounding APIs:

• writeAsync
• asyncWrite

One existed before Swift introduced its async/await syntax, and used callbacks.

The other was added to support async/await syntax.

1. Someone noticed this in the docs and was confused about which one to use. Which made me realize I need to do a better job disambiguating these in the docs.
2. I bolted on a lot of async/await stuff and it may be time for a holistic revisit of async functionality.

This is a good reminder of WHY you have to actively maintain docs. It’s very easy to add or update docs in one place, and miss resulting changes in other places.

I haven’t found a better tool for this than regular audits and gap analysis. But to do that effectively requires someone with good subject matter expertise who can spot things that have changed and need updates.

Tech writers, do you have good process around this? What is it?

Last week, I posted about how I used our fall hackathon at MongoDB to get Google Analytics data out of a spreadsheet and into MongoDB Atlas.

This week, I'm looking at how I transformed documentation metadata in Atlas to make it easy for us to get the insights we want. I look at what questions we want to ask, and what data we need to support those questions. And then dive into some practical aggregation pipelines to set up the data!

We had our fall hackathon at MongoDB last week! I decided to use the time to get Google Analytics data for the documentation that my team writes out of an unwieldy spreadsheet and into MongoDB Atlas, where I can more easily analyze the data and build useful Charts visualizing the data for my team.

In Part 1 of my 3-part series about my hackathon project, I look at how to get data out of Google Sheets and into MongoDB Atlas using Google App Scripts, a Data API HTTPS Endpoint, and an Atlas Function.

I recently wrote about why you should test the code examples in your documentation. That led to some interesting conversations - notably about who should be writing the code examples in your documentation.

After talking with other technical writers and engineers, I jotted down some of the benefits of having the documentation team writing the code examples. I'm sure I've missed some!

Do you have opinions about whether #TechnicalWriters or #Developers should be writing the example code in your docs? Tell me about them - I'd love to hear it!

Today I was musing about how we as #TechnicalWriters know when to update documentation. Are there processes or strategies you use to find out about changes to the product? Do you rely on product or engineering to tell you about upcoming changes? Are you embedded on teams where you're involved in planning and can decide for yourself when to update docs?

I had a few thoughts based on how I do things - including a tool I wrote to help - but I'm really curious how other #Documentarians approach this challenge.

Just a sneak peek of something I've been working on...

Are you a #TechnicalWriter who works with engineers who occasionally forget to mention when something needs a documentation update?

Are you a #Developer or #DocsAsCode technical writer who makes or reviews PRs, or is assigned work in GitHub?

PR Focus is a macOS app that lets you watch GitHub repositories, see new and updated PRs in those repositories, and "Watch" or "Ignore" pull requests depending on whether they may need some action from you. PRs automatically show up in your "Reviewing" or "Assigned" columns if you're a requested reviewer or assignee, or if you become a reviewer. When the PR is merged, you can decide how long it should continue to show up in the dashboard before it moves to "Archived" or you can right-click to dismiss it from your dashboard.

Gone are the days when you had to check on multiple different repositories to see what's new and updated. No more losing track of outstanding PRs that require some action from you. Just one awesome app to help you stay on top of PRs you care about.

My team is shaking things up and helping out with some wider docs projects, which gives me a chance to help out with the Realm Kotlin SDK docs for a bit.

This is my first time really touching Kotlin, and I probably would have been intimidated to try a few languages ago. But after branching out from Swift to help out with C++, Flutter, and now Kotlin docs, plus building tools in TypeScript and Python, I’m not intimidated to touch new languages anymore. And I’ve learned that if you know a set of APIs really well, it’s not that difficult to figure out how to use them in another language.

Still loving a job that constantly lets me learn new things and grow my skills. Grateful all the time for the recruiter who reached out to me in 2020 about a job that united my tech writing background with a chance to grow development skills.

This week is hubby’s first week at a new job after being laid off at the beginning of November. He’s been a developer for over 20 years and this is the longest it has taken him to find a job. Typically, when he changes jobs, it take less than a month.

It’s tough out there right now, folks.

Thinking of everyone who is looking right now. You’re not alone.

When you write for a living, your hands are your livelihood. I wrecked mine by typing thousands of words a day on a cramped laptop keyboard in my 20s. I switched to the Kinesis Advantage keyboard to reduce hand pain and prolong my working life, and eventually to the Advantage 2. But the fixed width still isn’t ideal from an ergo perspective, and the heavy case and wire doesn’t really fit with my modern minimalist desk setup.

Enter the Glove80, my new split bluetooth keyboard that arrived yesterday. I immediately had to remap a bunch of keys because I’m a nerd who uses a very customized key layout. But Glove80 made it easy, and even uses the same size keycaps for all keys so I can move them around to actually match my layout. First time in many years the labels on my keys actually match the layout.

Pretty psyched for this improvement! I suspect the Kinesis keyboard will be going away for good this weekend.

One of MongoDB's core values is #buildtogether . This is one of my favorites, because the end result is always something better than an individual could achieve alone.

As an example, I led a Docs Maintenance Working Group a while ago that attempted to systematically identify maintenance needs so we can proactively address them. One of the things we came up with was "remove unused files from our docs repositories."

My awesome lead @cbush not only extended a tool that he wrote to work with our docs repositories to identify files that aren't used in our docs - he also set up a GitHub workflow to run this tool on every PR. So any time we make changes that result in unused files, we get a reminder to remove those files from the repo. This is above and beyond the original ask of "remove unused files."

Also, this has had the follow-on effect of causing me to prune our code example unit tests to remove unused code examples and unused tests, reducing the number of tests to maintain and making the unit test suite faster to run.

This is why #buildtogether is so powerful. One person has an idea. Another person adds to it and makes it better. Follow-on effects amplify the impact.

It's so great to work in an org where we live our values every day, and those values have a real impact on the work we do.