Microblog

If you are a technical writer who documents software, learning to use your version control system's APIs is a force multiplier.

It's easy for Jira or other tracking processes to fall behind reality. When you document software, the code is the source of truth. So don't watch Jira - watch the code!

I learned GitHub's APIs to write PR Focus, an app that let me keep track of engineering feature PRs. Since I work in a docs-as-code workflow, it also let me easily stay on top of my work.

Since then, I've been writing little utilities that use GitHub's APIs.

I've got a script that gets traffic metrics from some public-facing code example repos we maintain. I write the metrics to a database which populates a dashboard for stakeholders. This lets us make data-driven decisions about developer engagement with code examples and how much we want to invest in maintenance.

This week, I added a script to check the release versions of the products we document and compare them against the versions we use in our test infrastructure. It automatically creates tickets for my team to update test infrastructure when we fall behind a release version.

Learn the APIs that can give you information about the state of code that matters to you. Code is the source of truth in software documentation - not Jira.

Reminder for all the technical writers and documentarians out there… your job has two components:

1. Doing the work you do.
2. Communicating about the work you do to other teams, leadership, the broader industry, etc.

Don’t neglect the communication! Your org needs to understand your work, the value you bring, and how it fits into the broader organization’s objectives.

Just finished writing some tooling to programmatically extract our hard-coded inline code examples out to separate files which can be included in the docs.

Code examples that are hard-coded inline in your docs may have been tested at the time they were added, but the moment you hard-code them inline, they become decoupled from the product and untestable going forward.

• You can’t test them with new SDK or API versions.
• You miss out on basic compile testing for valid syntax.
• You can’t use linters to standardize the formatting of your code examples.

If you value accuracy, consistency, and maintainability, don’t hard-code your code examples inline in your docs!

Links from the comments:

• https://github.com/cbush/docdoctor/pull/13

Continuing to think about code examples in documentation, and I'm starting to ideate around some core concepts, or "Pillars" of code examples:

• Coverage: How complete is the code example coverage within the documentation? Does every API have the right quantity of code examples, demonstrating usage at the right levels of abstraction? Do code examples show not just the API itself, but how to get/form the arguments for the API, and how to work with whatever the API returns?
• Maintenance: Are the code examples tested? Are tests run with every version update/code example change? Do tickets get generated to update code examples when APIs change? Is there a governance policy for archiving code examples for old versions?
• Discoverability: Can developers find your code examples? Are they available not just in your documentation, but in GitHub and/or LLMs? Do third-party sources have information that leads developers back to your code examples - i.e. package manager release notes, READMEs off your website, etc.?

Curious for your thoughts, #TechnicalWriters and #Developers - do these pillars resonate with you? Are there things I'm missing, or things you think are particularly important?

I got a lot of interesting and thoughtful replies to my post yesterday about code examples in docs, but I've got a hot take on one of the themes that emerged... that code examples should vary depending on the intended audience. (Skill/experience level, etc.)

That's a common convention in technical writing, but I have never seen this done effectively with code examples.

I have never seen a docs set that allowed me to specify my skill level - i.e. experienced developer who is new to this tech versus new developer. I have also never seen a docs set that effectively tailored examples for different experience levels.

I have seen docs marked "Beginner," "Intermediate," "Advanced." And I've seen from experience that docs writers are bad at assessing what should be in each skill level when it's generic like this, and developers are bad at self-selecting their skill level.

So - I think this theory that code examples should be different for different audiences doesn't hold up to any real-world docs sets I've seen.

Do you have a favorite docs set that you think actually implements this?

(I also have thoughts about the maintenance burden this requires. I made a proposal in my org earlier this year to single-source different levels of code examples from a single tested example, but haven't had a chance to go beyond proposal with this yet. I think it would be very easy to create a major maintenance burden if this isn't single-sourced from a tested example set.)

I’ve been thinking a lot lately about code examples in documentation.

What makes a good code example in a docs set?

How much should we break stuff down? Do you want code examples that are in separate files so they’re easy to reuse, or one big file so you can run it easily?

How realistic should a code example be - should it show error handling?

If you need to run code in incremental steps, should those be in separate examples, or should we give instructions about where to paste it into an existing example, or should it be commented out but present in the original example?

Does a single line count as a code example?

It’s amazing how few industry best practices exist around code examples, when they are such an important component in docs that are meant to teach developers how to use your APIs.

The next PR Focus release is almost ready, and it brings a focus on individual contributor workflows! There is a new "Principal PRs" dashboard that shows only:

• My PRs
• Assigned PRs
• Reviewing PRs

For folks who don't want to watch or ignore other pull request activity in a repository, there is a setting to make this the default view in PR Focus.

And! The extra real estate for the "My PRs" list means there's space to surface more actionable information in the pull request summary. So this release adds badges for "Approved" and "Changes Requested" directly to the PR summary, meaning you don't have to click into the details and can quickly scan for actionable updates.

This release is almost ready to go - there's one more small feature I'd like to sneak in. Hoping to have it ready over the weekend!

Naming things is hard.

I’m adding a new dashboard to PR Focus where people can view only the pull requests they’re involved in. This consists of two, or potentially three, lists of PRs:

• My PRs (PRs where the user is the PR author)
• Assignee PRs
• Reviewing PRs

“Mine” doesn’t work as a UI label, because most people would expect that to be just “My PRs” - not the assignee and reviewing columns.

I was thinking “Contributor”, but spousey argued you’re not really a “contributor” if you’re reviewing a PR - especially if you have only been tagged and haven’t reviewed it yet.

Spousey started suggesting acronyms - “CAR” and “RAM”, but I have SO MUCH resistance to an acronym as a UI label. I’m sure there are times where it’s the best option, but this doesn’t feel like one of them.

I have tentatively landed on “Principal” but I don’t love it.

Someone suggested “Active”, as a counterpoint to some of the other UI labels (“Inactive” and “Archived”), but there is another dashboard where you can watch PRs where you’re not a contributor, and those PRs could also be active. So that doesn’t work in the larger context of the app’s functionality.

Words are important. Getting the right word can sometimes be hard.

PSA: If you are storing static information in Discord, or requiring folks to join a Discord server to get information about your product, you’re doing it wrong.

Discord is a chat app.

If you have static information to convey, that does not belong in a chat app.

It should be a website.

Doubly so if the static information is documentation.

There was an interesting conversation in Write the Docs about a guided code experience where explanation is presented side-by-side with code examples. As you scroll through the explanation, the code example on the right changes to reflect the next step, where the relevant content is highlighted.

Apple has my favorite implementation of this guided code experience in their developer tutorials - here's an example: https://developer.apple.com/tutorials/swiftui-concepts/scaling-views-to-complement-text

Curious how many #TechnicalWriters are doing something like this with their docs? Do you have thoughts on this way of presenting code and content? Maintenance considerations?

My team has stepped tutorials with code examples, but the presentation is very different - I really like this side-by-side component.