Writing for Business and Technical Audiences

» 19 November 2022 » In Uncategorized » Comments Off on Writing for Business and Technical Audiences

Something a little different here.

While I was away, I did plenty of writing, but none of it was for public consumption. A major part of my job at large technology companies has been reading, writing, and editing documents explaining various issues and what can be done to address them. I think it’s a more important skill than people generally realize, as it may be the one way to reach someone in a different time zone, or who couldn’t make a meeting, or who you will never speak with in person. Effectively written documents also have a way of hanging around, so investing in them can pay back over the long term.

I’ve also learned through experience that there is value in good writing in ways that aren’t always obvious. A well-articulated error message in a log file or api response can save an engineer significant time, for example.

Over the years I’ve gathered a set of guidelines that have worked for me. I’ve made it a habit of sharing this type of stuff internally at the companies I work at, but none of this is specific to any company, so I’d like to share publicly this time.

This list benefited from feedback and revisions provided by professional colleagues of mine. I won’t name them here, but thank you to those of you who read drafts of this and offered feedback.

Know Your Audience

Know who you want to reach, what you need them to know, what context they have/don’t have, and what you want them to do with the information you will convey. Make it as easy as possible for them to get what you need from your communication. Be clear if there is a call to action or follow up you need from them, and by when.

Incidentally, probably the single biggest factor in the previous success of NPB Tracker was that I knew who I wanted to reach and inform.

Headings

  • Titles: Make your doc title meaningful and discoverable in search.
  • Email Subjects: Make the subject scannable so the reader knows whether they need to read and if there’s an action that they need to take.
  • Subheadings: use them to make your long document or email more easily scannable.
    • The subheading of a paragraph should summarize what the paragraph is about.
  • Write the names of the authors, contributors, and reviewers at the top of the document. Most templates have this. Do it for everything.
  • Include the date the document was started. I prefer the format YYYY-MM-DD because it is the international standard, and avoids ambiguity between the American and British formats. Spell out the month for extra clarity.

Introductions

  • If there is a specific proposal in the document, put it right at the top. This gives the audience the option to decide whether to read the whole document or not.
    • Example: “This document proposes developing a Twitter client for the Atari 2600 platform, funded with four SWE headcount and a target release date of June 1983.”
  • Set a clear expectation for the audience upfront. Sometimes I write a “How to read this document” section at the top to make this obvious.
    • Example: “this is a collection of notes on an early stage product, no major decisions are being proposed yet.”
  • As a rule of thumb, I normally write my introductions last, after I have written the rest of the document.

Content

This set of suggestions is primarily relevant to longer form documents, proposals, and emails.

  • Don’t make assumptions about what your audience knows. If assumptions are unavoidable, make it clear what the assumed knowledge is.
  • Define key terms that may be unfamiliar to the audience.
    • Example: “Atari 2600 is a video game console that was popular in America during the early 1980s”
  • Be as specific as possible.
    • Words such as many, almost, nearly, significantly, better, worse, etc imply different things to different people. Being specific takes away this ambiguity. 93% of bugs, increase of 7% performance, etc. The specifics also show that you are speaking from a place of knowledge instead of filling in content.
  • Follow the Amazon rules (source), particularly:
    • Replace adjectives with data
  • Avoid “weasel words” – words that are ambiguous or misleading. Examples, taken from Wikipedia, include:
    • “People are saying…” (Which people? How do they know?)
    • “It has been claimed that…” (By whom, where, when?)
    • “Critics claim…” (Which critics?)
    • “Questions have been raised…” (Implies a fatal flaw has been discovered)
  • Avoid inside jokes and pop cultural references in the core points of the document. These might increase engagement for some, but exclude others who aren’t in on the joke.
  • Read up on inclusive language and make sure you aren’t including outdated terms.
  • Put reference links in an appendix section.
  • Define acronyms, abbreviations and other key terms that reader may be unfamiliar with at the beginning of your document
  • Add visuals if possible – charts, graphs, architectural diagrams, etc.
  • Avoid condescending words (obviously, of course, clearly)

Editing

  • Edit your documents for clarity and correctness. Take a break between writing and editing.
  • Have a few trusted early draft reviewers, who can give you feedback before you share widely.
  • As a rule of thumb, I try to focus on removing unnecessary detail and content when I edit my writing, to amplify the most important points.
  • Remove redundancy. Are you saying the same thing 3 different ways?

Reading

  • Make time to read others’ documents.
  • Share interesting things you read with others.
  • Don’t be afraid to give positive feedback.

Continue reading...

Tanaka to Remain with Rakuten

» 09 November 2022 » In mlb, npb » Comments Off on Tanaka to Remain with Rakuten

Hey, let’s break some news again. It’s been a while.

Former Yankee Masahiro Tanaka has declined to file for free agency, and will remain with the Rakuten Eagles for next season. Tanaka had been under a two-year contract that ended after the 2022 season.

Quoted in Nikkan Sports, Tanaka commented “I’ve decided not to exercise my right to free agency, and remain with the Eagles next season. I feel that next season, I want to apply my whole strength and energy toward arriving as League Champion, and Japan Champion.”

There had been some speculation that Tanaka might take another swing at MLB, but it feels like that ship has sailed. Nikkan Sports also adds the detail that Tanaka and Rakuten had been talking about a contract for next year since the middle of the season.

Continue reading...

Tags:

What’s In The Works

» 30 October 2022 » In Uncategorized » Comments Off on What’s In The Works

One of my old habits as a writer was to make lists of the articles I planned to work on. I found that it kept me accountable to producing some level of work, even if what I finished wasn’t always what I started. Here’s what I have in mind for this iteration of NPB Tracker…

  • A look at the Yakult Swallows and the Orix Buffaloes, contestants of the last two Nippon Series.
  • How I would have rebuilt Yakult, basically a retrospective on what I said I’d do, but never did.
  • A look ahead at this upcoming NPB imports to MLB.
  • How baseball has changed for me, personally, over the years.
  • Muzak in Japan.
  • A review of the King Jim Pomera device.

In addition to the baseball content, it’s likely that I’ll work in some business and technology-related content into the site. I actually never stopped writing, but the majority of what I wrote was intended for business audiences, internal to whichever company I happened to be working for at the time. If some of that stuff is applicable to a general, public audience, it may show up here as well.

Continue reading...

Hello Again

» 21 October 2022 » In Uncategorized » 3 Comments

While I was away, someone else successfully rebuilt Yakult.

Continue reading...

Rebuilding Yakult: Part 0

» 14 September 2017 » In npb » Comments Off on Rebuilding Yakult: Part 0

Nine years ago, in June 2008, I started this blog with a post about long-time Yakult Swallows closer Shingo Takatsu. Un-relatedly, I found out a few weeks later that I had my first child on the way, a son who would be born the following spring. Six years later, in 2014, I took my son to see his first Japanese baseball game, a Swallows home game at Tokyo’s Jingu Stadium. The visiting team was my favorite, the Hanshin Tigers, and my intent had been to begin indoctrinating him into Hanshin fandom. Sometimes, however, the dots have their own way of connecting. The Hanshin side of the ballpark was mostly sold out, so we wound up on Yakult side, surrounded by Swallows fans. Mid-way through the game, I granted his wish for a pair of Swallows ouen bats, and when Yakult won he high-fived his new umbrella-toting friends, and a Yakult fan was born. We’ve been back to Jingu, as well the visitor section of Tokyo Dome, several times, and nearly every morning my son awakens with the question “did Yakult win?”

Unfortunately, the answer to his question has been “no” a horrifying 67% of the time this year.

Yakult being uncompetitive isn’t a surprise. My preseason predictions had them edging Chunichi for fifth place in the Central League; I knew their pitching would be suspect, but thought that they’d score enough runs to stay out of the cellar. I missed the mark on that one, as the Swallows’ futility has been all-encompassing this year. Yakult ranks as the worst in the league in pitching, hitting, and defense. These realities are thoroughly reflected in their winning percentage, which is the worst in Japan.

Prior to my son’s Yakult fandom, it’s likely that I would have taken minimal notice of the Swallows misery, and eventually forgotten about it as I have many other last place teams. But having a relatively newfound emotional connection to this team has gotten me thinking, what would I do to fix the Swallows? And that question has given me a vehicle to (modestly) re-launch activity on NPB Tracker.

Over the next couple months, I’ll write a handful of posts outlining what my prospective approach would be if it was my job to establish Yakult as a competitive force. Along the way, I’ll take a look at the moves they make and offer my point of view. The rough framework for how I’ll look at this is something like this:

0 Surveying the Landscape, Picking a Strategy (this post)
1 Finding a Manager
2 Heading into the Draft
3 Offseason Reinforcements
4 Internal Prospects
5 Foreign Imports
6 Spring Training

Surveying the Landscape

Japan’s Central League has six teams, which are currently ranked the way I expect them to finish the season:

1. Hiroshima Carp
2. Hanshin Tigers
3. Yokohama DeNA Baystars
4. Yomiuri Giants
5. Chunichi Dragons
6. Tokyo Yakult Swallows

Taking a more general view…

Hiroshima — looks poised to stay at the top for the time being
Hanshin — blend of unproven young talent and aging veterans who, so far, are holding up
DeNA — solid lineup, three key starters acquired in the last two years have kept them in the mix this year
Yomiuri — strong frontline pitching, aging lineup, always a threat to spend in free agency
Chunichi — strong track record in acquiring foreign talent, star players from 2003-2012 golden era have retired and not been replaced
Yakult — no pitching depth, injuries and non-performance have taken toll on offense

It’s looking like this is Hiroshima’s era; I don’t think they will necessarily rattle off a long string of championships, but they’ll be in the conversation for at least the next couple of years. The other four teams are all better than the Swallows at the moment, though they all have weaknesses. Even so, Yakult is a couple of years and a couple of good drafts away from making things interesting in Yoyogi again.

So the immediate goal is to simply be less of a doormat, and give the Jingu fans reason to raise their umbrellas a few more times in 2018. Longer term the goal is to build a team that can contend for an extended period of time. How? My take is that in building a team, one can either raise the ceiling, or raise the floor. I think the approach I prefer with Yakult is to raise the floor, to try to replace the team’s worst performers with average ones. Time will tell if I can identify a reasonable strategy to accomplish that.

First things first though. Swallows manager Mitsuru Manaka has stepped down, and we’ll need to find a replacement. We’ll cover that in the next installment.

Continue reading...

Questions To Ask Startups

» 28 June 2017 » In Uncategorized » Comments Off on Questions To Ask Startups

This is something very different. I have had the itch to write again for a while now, but real life has kept me busy enough that I can’t devote enough time to baseball to come up with anything interesting to say about it. So I’d like to write a little bit about my work experience, in the hopes that someone out there may find it helpful in some way.

Some of my remaining dozen or so readers probably know that I’ve spent the bulk of my professional career working at startups in Silicon Valley. Most of my experience has been in middle management, specifically of engineering and technical teams, and along the way I’ve learned a lot about what to look for in a startup as an employer. On my most recent trip through the job market, I made it a priority to join a quality company, so I came up with a list of questions to ask startups to try to evaluate whether they might pan out.

I ultimately decided against joining a startup, but having a framework for what I was looking for and how I was evaluating it helped me engage in better, more mature discussions with prospective employers. Although I specifically had pre-profit, venture-backed companies in mind when I came up with these questions, many of them could apply to any business. Here’s hoping someone out there finds them useful.

PRODUCT AND CUSTOMERS
1. What does the startup exist to do?
2. Who are the users?
3. Who are the customers?
4. What do they like about the offering?
5. What needs to get better?
6. What can customers get here that they can’t get anywhere else?

CASH AND FINANCES
1. Who are the investors?
2. How much runway is available?
3. What is the goal of the next round? Is the emphasis to grow and raise, or reduce burn and break even?
4. How transparent are the company’s finances to leadership, and the employee base?

LEADERSHIP
1. What is the CEO’s background?
2. What is the founding team’s role?
3. What are the CEO’s values? What values are shared among the VP/C-level?
4. What is the existing technical and managerial leadership structure?
5. What is the depth of skill and investment in each functional area (engineering, sales, etc)?
6. How transparent is leadership with success metrics, and opportunities and threats to the company?

ORGANIZATION
1. How is the organization structured?
2. Who has the most influence over product and technical decisions?
3. How are key decisions made, socialized, and instituted?
4. How strong is the second layer of leadership?
5. Is any house cleaning needed?
6. Are there candidates for career growth?

PROCESS
1. How ‘mature’ is the product development process?
2. Are successes repeatable and are failures turned into actionable improvements?
3. Are metrics defined? How widely available are they to the staff?

MY ROLE
1. What areas are in the most immediate need of improvement?
2. What impact do you expect this role to have on the team, offerings, and company?

EQUITY
1. How many shares are outstanding?
2. What is the strike price of shares issued in the most recent round of funding?
3. What is the vesting period?

Continue reading...

Why Japanese Baseball?

» 06 June 2017 » In Uncategorized » 2 Comments

In the nine years since starting this site, I’ve done dozens of interviews and talked to perhaps hundreds of fans, readers, and other writers. The question I get more than any other, by a wide margin, is some variation of “why Japanese baseball?”

I’ve occasionally told the story of how I was introduced to Japanese baseball but I’m not sure I’ve ever answered the question of why it’s appealed to me so much. I’ll try to do that here.

The starting point for me was my interest in Japan. At age 11 I picked up a video game magazine that happened to have an article in Japan, and that was it.

The first thing that hooked me on Japanese baseball was the novelty of it. It was baseball, but it was new and different. The pitchers had funky deliveries and throw off-speed stuff, the batters had more character than their MLB counterparts, the uniforms were different, the fields were different, the fans were entertaining.

As time progressed and I learned more about NPB and baseball in Japan, my appreciation for it grew. It sounds cliched, but the relationship between the players and the fans is different in Japan. NPB players are, for the most part, a bit more down to earth than players in American sports leagues. Hang about the Yakult Swallows’ Jingu Stadium before a game and you’ll see uniformed players and coaches going about their work, going back and forth between the practice field and the stadium amongst the fans and vendors.

It isn’t just the Japanese players who are down to earth. Most of the foreign ball players are journeyman, who are exceptionally good players, but not quite great enough for MLB. Most of them come across as legitimately grateful for their chance at playing in Japan, and I’m always happy to see hardworking players get a shot at establishing themselves in Japan.

The fans, in turn, are a bit more uniform in their support for their favorite teams. Yes, there are fair weather fans and some players are more beloved than others, but at games, the cheering vigor of the fans doesn’t drop from batter one to batter nine. I’ve found Japanese fans to be incredibly welcoming as well. At my first Kitetsu Buffaloes game back in 2001, the salaryman sitting beside me made sure I knew every player on the field, and bought me balloons for the seventh inning stretch balloon launch. Some variation of this has happened at many of the games I’ve attended since.

I feel like this explanation, so far, does a disservice to the quality of play. I won’t pretend the quality of play in NPB is MLB-caliber, but it is certainly good, competitive baseball. The best players have proven to be successfull at the MLB level, and even the role players usually have some redeeming skill. I’ve enjoyed appreciating in players; one guy may have a great throwing arm, another may have great bat control, another may be a bunting specialist.

Most North American fans look at leagues in Asia as sources of talent for Major League Baseball, and that’s fine, but NPB and KBO are good baseball leagues worthy of appreciation for their own merit. I started NPB Tracker primarily to combat incorrect information about Japanese players bound for MLB, but also to increase overseas interest in Japanese baseball. Over the passed nine years, the quality of information on Japanese players has improved dramatically. But I can’t measure any real uptick interest in the league itself from overseas, which perhaps should be next goal.

tl;dr: Japanese baseball is good because:
1. it’s fun and different
2. the bond between the players and fans is deeper
3. it’s good baseball

Continue reading...

Farewell Wayne

» 20 April 2017 » In Uncategorized » Comments Off on Farewell Wayne

Last Wednesday, I got an email from my friend John Gibson that long-time Japan Times baseball columnist Wayne Graczyk had passed away. I didn’t know Wayne personally, but his passing saddened me. Wayne was one of my early guides to Japanese baseball, and his work made the league accessible to before I learned to speak and read Japanese.

I didn’t know it at the time, but I first heard Wayne’s voice in 1994. The MLB player’s strike had cancelled the World Series, and my local sports cable station showed the Japan Series, broadcast by the White Sox announcers and some guy who lived in Japan. That guy happened to be Wayne, and although I didn’t remember his name, I absorbed much of what he had to say. And so began my fascination with Japanese baseball.

Fast forward to 2001, when I was a youthful English teacher working at a Nova chain school somewhere near Osaka. Every time a Japan Times shows up in break room, I would immediately flip to the sports section and read Wayne’s Baseball Bullet-in column. Life in Japan was still new, and baseball was both comforting in it’s familiarity and fascinating in its differences. Wayne had a deep understanding of Japanese baseball, and I learned through his work, bit by bit, until I learned Japanese well enough to get by.

Fast forward again to 2008, when I started npbtracker.com. I was working on a blog post that was a collection of links, and I decided to call it “NPB Bullet Points,” as a nod to Wayne’s influence on my work. The name stuck and I wrote dozens, if not hundreds, more posts using that title.

I think that Wayne knew that Japanese baseball, like most things, could be enjoyed more thoroughly with a deeper understanding of it’s culture, nuances, and history. This was certainly reflected in his writing, and I’ve always tried to carry on the tradition in bringing Japanese baseball to new audiences.

I never met or exchanged emails with Wayne, but without his work, my development as a writer would have taken a different path. My condolences go out to his family, friends, and loved ones.


I never got to thank Wayne personally for his work. I’m lucky to have met my other early influences in Japanese baseball, Jim Allen and Michael Westbay, multiple times, and happily call them friends. But I’d like to show my appreciation to them once more, and say thank you. Without the work Jim, Michael, and Wayne have done to make Japanese baseball accessible to English-speaking audiences, there certainly would never have been an NPB Tracker.

Continue reading...

JBW 200

» 19 October 2015 » In npb » 1 Comment

200. That’s how many editions of the Japan Baseball Weekly Podcast John Gibson and Jim Allen have released. If you haven’t checked it out, you’re in for a treat, JBW is perhaps the best kept secret in the baseball media. Having appeared in some form on about 10 of the 200 podcasts, I know exactly how much work goes into the planning and production of the show, which only increases my admiration of Jim and John for keeping it going for five years. Congratulations guys on 200 shows, and here’s to the next 200!

I missed my cue for my favorite JBW memories, but I have two, neither of which is a specific show. The first is that from June 2013 through April 2015, I had a job that required me to commute about an hour and a half each way, mostly by train. It was a long, and frequently exhausting, commute, and the JBW podcast helped pass the time. The second is just simply talking baseball with John and Jim the times I’ve made appearances. It’s always a lot of fun, and it’s great motivation to drag myself up and force myself to enjoy some baseball.

If I had to pick a memorable show, I think I’d have to go with this year’s Pacific League predictions series, which I appeared on with Claudio Rodrigues of Beisbol Japones, whom I had never met before. It was a great, rousing conversation, and there’s a funny story behind it, which I’ll let John decide if he wants to share.

And with that, I have episode #200 embedded for your listening pleasure right here. Listen for John making fun of me within the first two minutes of highlights 🙂

 

Continue reading...

Tags:

Who’s Gonna Win?

» 13 September 2015 » In npb » Comments Off on Who’s Gonna Win?

On September 13, 2015, the Central League achieved symmetry. Yomiuri beat DeNA 3-0, Chunichi tied Yakult 2-2, and Hanshin lost to Hiroshima 0-3. This is something of a microcosm of how the Central League pennant race has played out. For most of the second half of the season, Hanshin, Yakult and Yomiuri have taken turns holding first place, while Hiroshima hovers a few games back. Over the last two weeks, the race has tightened up even further, with four teams within 3 games of first place, and the top three locked in tie-like conditions.

(Standing as of Sept 13)

# Team W L T GB
1 Yakult 65 60 2
2 Hanshin 65 61 2 0.5
3 Giants 66 62 1 0
4 Hiroshima 61 62 3 2.5

So who’s gonna win?

It’s still anyone’s pennant.

Remember that in Japan, the champion is whoever loses the fewest games, so this race is maybe even a little more neck and neck than it appears. In pretty much every game, each of the four contenders a chance to add to their win column, but also bump up an opponents lose column. But in doing so they also help their other rivals.

Erm, so who’s gonna win?

Let’s also point out that the top three placed teams will qualify for the playoffs, but the league champion gets a bye in the first stage of the Climax Series playoffs, and a one-game advantage in the second stage. Given the parity of the teams this year, that’s a big prize.

Right, okay, who’s gonna win?

Yakult wins if… their starting pitching holds up through the rest of September. The Swallows have been on a bit of a run lately, going 9-3-1 over the last three weeks. Over that stretch, rainouts and off days have allowed them to rely almost entirely on four starters: Yasuhiro “Ryan” Ogawa, Taichi Ishiyama, Masanori Ishikawa, and Shohei Tateyama. Over the second half of September, the Swallows will have 11 games over a stretch of 13 days, and will probably have to dig a little deeper in to their rotation, especially as Tateyama is returning from his third Tommy John surgery. A well-timed gutsy performance from a guy like Hirofumi Yamanaka or Orlando Roman could be the difference between a league title and a third-place finish. Key players: Yamanaka, Roman, Tateyama’s current ulnar collateral ligament.

Hanshin wins if… they can keep Hiroshima at bay, which they have so far not managed to do. Hanshin is 7-12-2 on the season against Hiroshima, but more importantly entered September with nine of their last 27 games to play against the Carp. So far five of those nine games have been played, and Hanshin is 1-3-1. Unfortunately for the Tigers, three of the remaining four games are on Hiroshima’s home ground, so their work is cut out for them, but they have to find a way to put a few losses on Hiroshima’s ledger. Aside from that, Hanshin has four more games against DeNA and Chunichi, whom they’ve enjoyed beating up on this year. The Tigers need take full advantage of their remaining opportunities to pad their record. Key players: Matt Murton and Mauro Gomez.

Yomiuri wins if… they can gain the upper hand on Yakult. The Tokyo rivals are an interesting matchup; Yakult having the league’s best offense, and Giants being the most adept at run prevention. The Swallows and Giants have perfectly split their 20 meetings so far this year, and have five left to play. Yomiuri’s pitchers have done a good job at keeping Yakult off the board, holding them to 3.1 runs per meeting, compared with their season average of 3.99. But they need to score runs to win, and in nine of their 10 losses to the Swallows, Yomiuri’s offense has put up three or fewer runs. Key player: anyone who happens to be holding a bat.

Hiroshima wins if… they can continue to beat Hanshin, and Yomiuri and Yakult trade wins with each other. After a vexing, underachieving season, the Carp have finally pulled up to the rest of the pack, though they are still on the outside looking in. The key to the remainder of Hiroshima’s season is sort of the inverse of Hanshin’s. They need to continue their success against the Tigers, and reverse their luck against the bottom-dwelling Dragons and Baystars. They Carp might be in first place if it wasn’t for their incompetence against the Central League’s worst two teams, whom they are a combined 16-26-1 against.  But if they can make that record look a little better over the seven games they have left against those two teams, they’ll obviously be in better shape. Key player: Brad Eldred. The Carp seem to win when he hits.

My prediction: I didn’t write it down at the time, but my pre-season pick was Hiroshima and I’m sticking with that. I’m giving them the league, beating Yakult’s winning percentage by a fraction. Hanshin stands to lose the most if Hiroshima succeeds, so I’ll pick them for fourth, with Yomiuri defaulting to third position.

Continue reading...

Tags: , , , , , , , ,