community techpubs work writing

Influencing community documentation contributions

After a week with leaders in the OpenStack community, taking leadership training, I’m inspired to write up ideas from Influencer: The New Science of Leading Change. For me, who needs to make the most out of community efforts, the idea that no one likes being told what to do was a familiar phrase. Rather, compel people to pick up your vision and add to it.

As an example, people often ask me, how do you motivate people to write documentation for open source projects? Or write for any software project?


Get details about the behavior you want to see

Using the framework this book offers, you first want to identify the behavior you want to see. Their examples often revolve around healthcare, such as hand washing. But you can get very specific about hand washing, such as where, when, and how. For documentation, you may say the behavior is “write” but I want to get more specific than that. Where should they write? Is the behavior “write a personal blog post?” Or is it “write in the official docs?”

Also, when should they write? Ideally as close to when the technical detail is still fresh as possible. The “when” could be at the end of a cycle when people are less distracted by feature additions. Or write documentation before the code is written and revise it often.

As for “how” do we want contributors to write, well, we may need to have templates and frameworks for the “how” — such as source formats, build jobs, and in which repo.

Looking at the behavior we want to see, getting super detailed about it, we find that we also want to encourage the behavior of code reviewers to read and review related docs.

Identify a crucial moment

Now, when a bit of code changes that makes a difference in the docs, that’s a crucial moment for influencing a particular behavior. The behavior we want to see is writing documentation while the code is fresh in your mind.CC Jonathan Cohen

Another crucial moment to engage is when a user first tries the feature; their fresh eyes may provide an update to the docs that others might not see. The “Edit on GitHub” feature of creating a pull request provides that outlet for fresh eyes to make a quick edit to the documentation.

So we have an idea of the behaviors we want to see, and a sense of when we want to see them. Now we can begin to ask what’s preventing the behavior.

Why don’t people contribute?

Let’s talk about: what’s painful about writing documentation? For example, if you speak English as a second language, it may be painful to write for others to review and the criticism might be more than you can bear. Kind, empathetic coaching, respect, and a culture of acceptance helps with this barrier.

Provide guidance and energy

Also, people associate boredom with docs. They look at a blank screen and can’t come up with words to describe their feature. They yawn and check their Twitter feed instead of writing docs. This pain point is where templates can help. People who don’t know what to write might need guidance, suggestions, or strict form-based templates.

Avoid context switches

It’s painful to have a doc tool set that’s extremely different from what you write code in — the context switch even to a web-based editor may be too big a barrier to jump over. Make the docs like code whenever you need to compel developers to write.

Get some influencers who believe in the vision

Without actual peer pressure that says “yes, we write the docs” developers may not create a culture that requires documentation. Start with the influencers in their peer group (which might not be you). For example, when a seed researcher wants to introduce a new hybrid seed corn, he goes straight to the local diner where the most experienced and influential farmer gets breakfast on Saturdays. It’s better to have the farmer in his pickup truck understand and believe in the benefit of changing to a new hybrid seed corn than for the researcher in his late-model Volvo.

Offer deliberate practice sessions

Also consider “deliberate practice” where you set aside time to get better at a skill. If the skill is writing, then have office hours or coaching sessions online, and at conferences make sure you can meet with people who want to become better writers to show them how to practice writing through drills, exercises, and with fun collaborative efforts such as doc sprints. Record a video or host an online hangout, showing all the steps for contributing deliberately and strategically.

Thanks to many coworkers who helped me discuss and think more about these ideas along the way. What are some additional ways to influence a desired outcome?


The journey is the reward

cc-by-2.0I’m re-reading Playing Big: Find Your Voice, Your Mission, Your Message by Tara Mohr. I’m at a certain transition point in my career journey which is taking me to a new role, a new team, and a new company. Reading Playing Big gives me a new framework, separate from Lean In, to think about how women shape careers and journey through life. And my journey has been and continues to be a great one: after a lot of consideration, I’m taking a compelling new opportunity at Cisco.

Rackspace has been a wonderful home for over five years, and I want to dive even deeper into developer experience: developer tools, outreach, and support (including docs, naturally). I want to study developer workloads for OpenStack infrastructure. I’m super excited for the amount of learning I can do at Cisco by joining their cloud group. I’ll still be working on OpenStack upstream and looking for ways to apply what I learn.

I write about it here so you can observe the transition not just on LinkedIn or Twitter, but also as a transition from tech writer to something new. I have a compelling journey to define.


Interface means integrate

I attended the Austin Homegrown API meet up at Wright Bros and Brew last week. Titled “Where the Rubber meets the Road,”—heh—there were about 25-30 people there, about half API-oriented and half car-oriented. Honestly, with interfaces and integration as a theme, all attendees were API-oriented. One of the people there simply to network had lunch with Lanham Napier (former Rackspace CEO) that very day, pitching his startup, though he never said what it was. Must be stealth time for his startup. Felt like quite the Austin moment.

carserv-logoThe format was two talks, the first was from a startup in Austin, CarServ. He showed their early findings when using the Edmunds Vehicle API to write an application that small maintenance shops can use to find out what maintenance any car needs. Their REST API contains a lot of data and this startup wants to make that easily available to non-dealership service providers. It’s a Ruby app. Edmunds provides a registered trademark “True Cost to Own” and “True Market Value” and I think someone should build a calculator for “True Time to Sell” based on service recommendations. (Someone do this!) The developer said they’ve had great response from Edmunds any time they’ve asked for increased rate limits.

The second talk was an API mashup with the Uber API and Google Calendar API “to make sure I’m never late again.” This was with Keith Casey about his proof of concept and it was fantastic, because it’s meant to be more thought-provoking than code-complete. I especially appreciated that he’s not exactly a fan of Uber’s business practices. The blog post at has more info, and the code is here: He already got contacted by a product manager at Uber but doesn’t plan to work further on the idea. To me, the city planning discussions are as interesting as the mashup itself.

I was one of three women there, I believe, and there were three lawyers, one of whom was a woman, so there was a interesting mix. I think they were interested in the Edmunds data API legalities with data re-use. For sure there were job seekers there. Did you know that actual car designs have 450,000 requirements that have to be tracked? Yipes, that’s a whole other level of complexity in design.

All in all, a thought-provoking meet up with a great mix of technologists who think like entrepreneurs. Integrate, innovate, interface, repeat. The next Austin API meet up is April 6th at Capital Factory.

API work writing

Playing with technology

One of the greatest parts of my job is getting to learn, write, learn write in a never-ending pattern. I got to play with Docker Swarm on our Carina offering at Rackspace and wrote up this blog post. It’s a tutorial for using Carina to create a Jawbone App with node.js. You can see the results at



While looking for a data-driven REST API for that tutorial I came across Mashape, which has a marketplace for APIs. I found the “They Said So” quotes API while looking around for a word-nerdy data project next. I could also try out the Merriam-Webster Dictionary API and of course, the best word-nerd API there is, Wordnik. So much data, so little time.

I find it fascinating that these API marketplaces are popular. Mostly when I ask developers about the usefulness of a site like Mashape they can’t come up with a great use case. I wonder if discoverability of APIs is an important part of promoting and educating people about your API. I think that with more and more API definitions, there is more and more need for discoverability. And of course, documentation. Opportunity abounds.

Why use GitHub as a Content Management System?

GitHub is a website that gives a user interface to source control. The tagline on the site is “Social Coding,” and I find that phrase to be an excellent summary of why GitHub is so useful for collaborative documentation. When writing for developers, write with developers, and believe me, developers are using GitHub for writing and coding. Like many tools, git and GitHub were created by fire—through a pressing need in 2005 for high-throughput and efficient source control management for the Linux kernel.

GitHub is the web interface, and git is the command-line tool that you use to copy files locally and track them. It’s cross-platform, so it works on Windows, Mac, and Linux operating systems. The biggest difference between git and other source control systems is that it merges files with a best guess rather than a “lock and checkout” model. The best guess for merging is often accurate but does require human inspection when the changes are too close to tell. The non-linear branching model means that you can experiment with many changes but still get back to a known state.

Here’s a brief vocabulary list for GitHub.

  • A repository is a collection of stored code or source documentation. For example, openstack-manuals.
  • A branch is an indicator of divergence from base. For example, the stable/liberty branch of openstack-manuals.
  • A commit is a point-in-time snapshot of a repository with changes. For example, this typo commit.
  • A fork is both an action and an object: forking is when you copy a repository, and a fork is a copy of a repository.
  • An issue in GitHub is a way to report defects, tasks, or feature requests. For example, an install article issue.
  • An organization in GitHub is a collection of repositories. For example, Rackerlabs contains Rackspace repos.
  • A pull request is a comparison of edits to see if the reviewing team wants to accept those changes into the main repository. For example, this pull request for a Rackspace page on

GitHub has some offerings that cover a couple of different use cases. Private repositories on the public site are about $7/month as a subscription and let you mark a repository as private and only invite trusted collaborators. GitHub also has an enterprise offering where the entire website is hosted where you want it and branded with your domain name. With GitHub Enterprise, you can ensure only company employees can access the source and collaborate with each other. Look up more options and pricing information on

Why use GitHub instead of a traditional CMS for docs?

When you are collaborating with technical people on distributed projects, often they are already accustomed to a GitHub workflow. So applying that workflow to technical documentation related to the project is a natural fit. Also, since GitHub has flexible review processes and prioritizes continuous integration, applying those benefits to documentation reviews and builds gives you the benefit of content management while bridging to sharing knowledge with subject matter experts. GitHub is a great match for when developers are writing documentation in source control. GitHub works well when a project is so large or distributed that no one person can know enough to write the documentation for the project. While GitHub is often associated with source control, the collaborative aspects go well beyond the traditional source control and CMS models.

In OpenStack, we have documentation workflows that mimic our code collaboration. We post patches for people to review, we review each other’s patches (similar to a pull request on GitHub), and we have build and test automation for every doc patch. The idea is to use the collaboration available in the GitHub pull request workflow for docs as well as code. We’re all responsible for relevant and accurate documentation for about 25 OpenStack projects written in Python across 130 git repositories, so let’s work together.

I do get questions from writers who are getting started with these types of workflows, so I wanted to bring together some of the best practices we’ve found, and find more. Here are two articles that serve the purpose along with a slide deck from a presentation I gave this year.

community work

Google I/O 2015, Looking Back and Forward

I wore my Google I/O t-shirt the other day while hiking, and realized I hadn’t posted a write up from that developer conference back in May 2015. This year they had a big push towards bringing women to the conference through effective methods.

Google has an Android developer community called Women Techmakers, led by Natalie Villabos. She did an amazing job with the event itself, but what most impressed me was the building of community prior to the event through the use of Slack, emailed communications, and networking opportunities both online and in person. Natalie said they went from 10% female attendees in 2013 to 23% this year. The first night I went to a Women Techmakers dinner was at an amazing Peruvian restaurant. The giveaways were lovely zippered canvas bags with Adafruit’s Gemma wearables package for hacking on later, which is awesome. I got the system working the other night, and ordered an additional soft potentiometer hoodie pull so I can make this project with the hoodie I bought at the conference.

Gemma kit

This article offers a good overview of what they did to get more women to I/O. Here’s a short list:

  • Grants
  • Hackathons
  • Nominations from Googlers
  • Reserved invites to women coding groups
  • Dinners together
  • Network enablement such as a Slack channel before and after the event

I sat with three women at dinner: one is an engineer at Quora in SF, about a year out of college, the other was a product manager at Fox News in New York City for their app work, and the third I spoke to most is a developer at

Faves and Raves

On Tap Now demo — or, how to not lose 20 minutes to your phone — was an example of a truly amazing context search. First, it brings us back to why we love Google in the first place. Second, she had a Skrillex song up and said, “OK Google, what’s his name.” I kid you not, I audibly gasped when it “just worked” and said “His name is John Moore.”

Expeditions gives Cardboard/VR to kids in classrooms. I went to this demo and it was pretty cool, we all sat on 360-degree swivel stools and turned to see what the “teacher” pointed us to in the VR screens. It was like having a fancy view finder. We went to Versailles in France, which I had very recently visited. It was impressive, but one aspect that threw me off was the cameras must have been super high off the ground. The Hall of Mirrors felt like I was floating through it rather than walking through it. But wow, what a cool experience for a classroom of kids. My second grader absolutely LOVED this.

Jump gives 16 cameras to do VR recording (Go Pro made one), Google assembler then makes it so you can interpolate the viewpoints and get 3 dimensions (depth-corrected stereo). gopro jump
I just read an article that said YouTube supports Cardboard for its videos now, here’s the help page.

Developer advocacy observations

Half the dev sessions were in these “alcoves” which were rooms created with cardboard tubes and boxes. It made for difficult hearing the presenter, even with mics on. Basically, no one left their comfy seating, so it was extremely hard to go around to different sessions.
cardboard alcove

I went to a Firebase demo, which had a great example of a developer advocate trying to identify with audience and do story telling. They did an example app that’s a chat application in a web browser that the audience could interact with right there. He could also turn the example chat off quickly if the crowd got out of hand in playing with it live. Side-by-side display made for a great demo as the noSQL updated before our very eyes.

Women at conferences, what’s in store?

As I reflect back on what it was like to go to a large tech conference with at least twice as many women as any I’d been to, I felt like the proof in the techniques to get us there is going to be in the return rate and the new signup rate. Will women feel like it was “their” conference too? Will they be annoyed with the overcrowding and not feel like it’s worth the extra effort to get on a plane? Will women keep returning because they’re there with their friends and it’s a tradition? Will women be more likely to spread the word about the conference itself to a wider group than just developers? I heard a woman explaining Google I/O to a man on the BART transit back to the airport, and thought, I haven’t seen much of that type of evangelism to the general public before. I think it’s going to take a while to see the effects of the special outreach efforts. I definitely think the diversity in networking effect is going to make a lasting change in the system. I sure hope so.


Lastly, I give you a great tweet from the guy in the hat in this picture said it with tongue in cheek, “14.2% men in tech at #io15.”
14.2 % men at Google I/O

Here’s the code lab I worked through.

Here are talks I watched later:

To tell even more of the story, here are all my photos from Google I/O, appropriately uploaded to the announced-at-I/O Google Photos, with captions.

techpubs writing

Treat Docs like Code: Doc Bugs and Issues

This is a follow on to a post on about using git and GitHub for technical documentation. In the article, I discuss reviews and keeping up with contributions. This post talks about fixes and patches.


What about doc issues in GitHub, how do you get through all those?

In OpenStack, we document how to triage doc bugs, and that’s what you need to do in GitHub, is establish your process for incoming issues. Use Labels in GitHub to indicate the status and priority. Basically, you have to accept that it’s a doc bug, if it’s not a doc bug, ask for more information from the reporter. If you want to create labels for particular deliverables, like the API doc or end-user doc, you can further organize your doc issues. You will need to define priorities as well — what’s critical and must be fixed? What’s more “wishlist” and you’ll get to it when you can? If you use similar systems for both issues and pull requests you’ll have your work prioritized for you when you look at the GitHub backlog.

How can you encourage contributors to create a good pull request for docs?

The best answer for this is “documentation” but also great onboarding. Make sure someone’s first pull request is handled well with a personal touch. There’s a lot of coaching going on when you do reviews. Ensure that you’ve written up “What goes where” as this is often the hardest part of doc maintenance for a large body of work that already exists. This expansion problem is only getting harder in OpenStack as more projects are added. We’re having a lot of documentation sessions at the OpenStack Summit this week and we’d love to talk more about creating good doc patches.

One person I work with uses GitHub emojis every chance he gets when he reviews pull requests. I think that’s fun and sets a nice tone for reviews.

Nitpicking can be averted if you point to your style guide and conventions with a good orientation to a newcomer so that new contributors don’t get turned off by feeling nitpicked.

Have you heard of anyone who has combined GitHub with a different UI “top layer” to simplify the UI?

O’Reilly has done this with their Atlas platform. For reviews, the Gerrit UI has been extremely useful to a large collection of projects like OpenStack. There’s Penflip, which is a better frontend for writers than GitHub. The background story is great in that it offers anecdotes about GitHub being super successful for collaborative writing projects.

I think that GitHub itself is fine if your docs are treated like code. I think GitHub is great for technical writing, API documentation, and the like. Academic writers haven’t found GitHub that much of a match for their collaborative writing, see “The Limitations of GitHub for Writers” for example. It’s the actual terms that have to be adapted and adopted for GitHub to be a match for writers. For example, do you track doc bugs (issues) and write collaboratively with added content treated like software features? I say, yes!

If you just want simple markup like markdown for collaborative writing, check out Beegit. With git in the name I have to wonder if it’s git-backed, but couldn’t figure it out from a few minutes on their site. Looks promising but again, for treating docs like code, living and working with developers.


Male allies for women in tech: What’s needed?

I realized the other day that I have given my “Women in Tech: Be That Light” presentation a half a dozen times in the last year. One question that I still want a great answer for is when a man in the audience asks, “What can I do to make it better? How can I be that light?” I have ideas from my own experiences, and also point to the training courses and Ally Skills workshops offered by the Ada Initiative. Updated to add: Register now for the Monday 5/18 workshop at the OpenStack Summit in Vancouver!


On a personal level, here’s my short list based on my own experiences. My experiences are colored by my own privileges being white, straight, married with an amazing partner, a parent, living in a great country in a safe neighborhood, working in a secure job. So realize that even while I write my own experiences at a specific place in my career, all those stations in life color my own views, and may not directly help people with backgrounds dissimilar to mine.

What do women in tech need? How can I help?

  • Be that friendly colleague at meetups, especially to the few women in the room, while balancing the fact that she probably doesn’t want to be called out as uniquely female or an object to be admired. If you already know her, try to introduce her to someone else with common interests and make connections. If you don’t already know her, find someone you think she would feel comfortable speaking with to say hello. It’s interesting, sometimes I’m completely uncertain about approaching a woman who’s the only “other” woman at a meetup. So, women should also try to find a commonality — maybe one of her coworkers could introduce you to her. For women, it’s important make these connections in friendly and not competing ways, because oddly enough, when I’m the second woman in the room I don’t want to make the other woman feel uncomfortable either!
  • Realize that small annoyances over years add up to real frustration. I don’t point this out to say “don’t be annoying” but rather, be a great listener and be extremely respectful. Micro annoyances over time add up to women departing technical communities in droves. See what you can do in small ways, not just large, to keep women in your current tech communities.
  • For recruiting, when new women show up online on mailing lists or IRC or Github, please do answer questions with a “there are no questions too small or too large” attitude. I never would have survived my first 90 days working on OpenStack if it weren’t for Jay Pipes and Chuck Thier. Jay patiently helped me set up a real development environment by walking me through his setup on IRC. And since he was used to Github and going to Launchpad/Bazaar himself, he didn’t make me feel dumb for asking. Chuck didn’t laugh too hard when I tried to spell check the HTTP header “referer” to “referrer.” I felt like any other newbie, not a “new girl” with these two. (Woops, and I should never use the term “girl” for anyone over the age of 18.)
  • Recognize individuality when talking to team members, regardless of visible differences like gender or ethnicity. I struggle with this myself, having to pause before talking about my kids or my remodeling projects, since not everyone is interested! I struggle with assumptions about people all the time, and have to actively fight them myself. For men, you don’t want to assume an interest in cars or sports, so really this applies regardless of gender. All humans struggle with finding common interests without making assumptions.
  • See if you can do small, non-attention-drawing actions that ensure the safety of women in your communities. With the OpenStack Summit being held in different cities twice a year, I’ve been concerned for my personal safety as a woman traveling alone. Admitting that fear means I try to be more savvy about travel, but I still make mistakes like letting my phone battery die after calling a cab in another city after 11 at night. If you see a woman at a party alone, see if you can first make her feel welcome, but then also ensure there are safety measures for her traveling after the event.
  • If you see something, say something, and report correctly and safely for both the bad actor and target. This is really hard to do in the moment, believe me, I’ve been there. For me, being prepared is best, and knowing the scenarios and reporting methods ahead of time gives me the slightly better confidence I can do the right thing in the moment even if I’m shocked or scared. Find the “good and bad” ways to deal with incidents through this excellent Allies_training page.

If you’ve read this far, you really do want to make life better as a male ally. Realize that it’s okay to make mistakes — I’ve made them and learned from them over the years. This inclusion work by allies is not the easiest work to do, nor is it rewarding really. It’s the work of being a good human, and we’re all going to screw up. If someone points out a foible to you, such as saying “girls” instead of “women,” say “thank you” and move on, promising to do better next time.

If you think you already do all these things, make sure you look for ways to expand your reach to other minority groups and less privileged participants. I’m trying to do better with the physically different people I encounter at work. I would like to find ways to work well with people suffering from depression. I’ve got a son with Type I diabetes, what sort of advocacy can I do for people with unique medical needs? I’m asking myself how to make a difference. How about you? How can you do your part to equalize the tech industry?

work writing

Be sure to read about my Stacker journey

The editors at The New Stack do great things with their articles, and mine is no exception! Be sure to read Anne Gentle: One Stacker’s Journey.

Even though I’ve lived in Austin, Texas, for over 14 years now, I tend to say I’m a midwesterner when asked. There are traits associated with the spirit of the midwest that I’ll always identify in myself: hard work, resource creativity and conservation, humility, and a sense of wonder at trends being set somewhere in the world. Read more…


State of the Migration to Sphinx/RST

I wanted to document the migration journey while we are in the middle of it. Last week the OpenStack Super User site did a great article about the migration, How you can help with the documentation site refresh. We talked about the reasons for it: enable more contributors, offer simpler markup, be more Pythonic.

And more Pythonic we are. Let’s dig into what’s going on with the migration, what we’ve learned, and what we still have to learn.

Migration process

We’re nearly done with patches to review converted End User Guide files, but just a few Admin User Guide files are complete. Sign up on the OpenStack wiki at Documentation/Migrate. I’ve figured out how to include certain files in a build conditionally with an extension we’ll call “scope” for now. Using (and abusing) the meta information by putting a special directive in a file meant for admin-only lets us “tag” certain files for inclusion and build output with those files included.

New content page design
New content page design

How to build locally

We have always had tox jobs for building and testing the docs. The newest one runs the sphinx-build command for the end user guide.

If you don’t want to use tox, install these prereqs locally to test only the build:

pip install sphinx; pip install openstackdocstheme

Next, switch to the directory containing a and run:

sphinx-build /path/to/source/ path/to/build/

This command builds html output by default.

In troubleshooting some markup I found that the sphinx-build command does not give as much information about the markup as python build_sphinx does. So I will test a switch with a file as well as a file for each guide in the openstack-manuals repo.

To build locally with tox, follow the instructions on the wiki page. Building with tox is preferred as that matches our gate tests for patches. Feel free to ask for help in #openstack-doc on freenode IRC if you run into errors. We have tested the instructions on Linux, Mac, and Windows.

Conventions and editing RST markup

Docs tools guru Andreas Jaeger already had a head start in adding RST markup conventions to our Documentation/Markup_conventions wiki page on the OpenStack wiki. I’m finding that there are some types of content, such as extra information embedded in a list item like a table, that just can’t come over in its current state. I’m still working through these questions and it seems as though numbered lists can’t have much more than single list items. Anyone with info, please let us know if these are possible:

  • How to get numbered list continuation to work when you have a table after a #. list item?
  • How to get numbered list continuation to work when you have a bulleted list between #. list items?
  • How to get get embedded .. note: directives to work between numbered list items?

Matt Kassawara asked if there is a side-by-side editor for RST like there is for Markdown, and so far there is not, but the Sphinx development mailing list has a thread about what authors currently do as well as what they’d like to build.


We still need output bugs fixed. To me, the top priorities are:

  1. Sphinx template needs precise “Log a doc bug” link created on-demand similar to current functionality
  2. Sphinx openstackdocstheme needs to be tested for the translation toolchain
  3. Sphinx openstackdocstheme doesn’t style admonitions (note, warning, important) correctly
  4. Plus sign appearing when numbered list followed by bulleted list

What I need to understand is what would compel us to update Sphinx itself, considering we don’t know when their next release is. We already pin to a beta version (1.3b) so perhaps  we can patch as needed and pin our version.


Generally, make sure your Python environment is installed and ready to go, and then use a virtualenv to be sure you have “corded off” the environment and know exactly what’s installed.

Use “pip freeze” to get a list of what is installed. If a package is missing, make sure you have access to pypi by running the pip install command with -vvv. Also if you’re not working in a virtualenv, ensure you run the install command with sudo on Mac or Linux.

If you’re working within a virtual machine like VirtualBox, you may find that networking settings change even if you go from wired to wireless or from one wireless network to another.

If the output looks strange to you, delete the /build/ directory then re-build. I suspect that CSS and JS files remain outdated or are not copied over every time.

Please log bugs in openstack-manuals with the tag “openstackdocstheme” if you see bugs in the output.

What this means for new guides in progress

The only new guide in progress is the Networking Guide and some of it’s in markdown, some of it’s in DocBook, and all of it can go to RST. We must get the translation toolchain working prior to publishing, and I’d prefer to get more output bugs fixed prior to switching any more guides.