Blog

Most of these posts were originally posted somewhere else and link to the originals. While this blog is not set up for comments, the original locations generally are, and I welcome comments there. Sorry for the inconvenience.

Transitions

Ten years ago I joined a company with a small-company feel despite being owned by a large company. The parent company let us operate pretty independently, the product was good, the team was excellent, and all was right with the world. The doc team at the time was large, about a dozen people including some community-facing folks (active forum, blog, etc), and was part of the R&D organization as is proper. The developers were easy to work with and there was a culture of learning and reaching beyond the limits of the job description. I was the first member of the doc team to commit changes to the code repository. (I was only changing comments that fed API documentation, but this meant getting a dev environment and learning how to run the unit tests and so on, all stuff I was quite happy to do.)

A few years later our parent company split, and then a couple years after that we were spun off and merged into another company. This is more corporate churn than I am used to (even though I've lived through several acquisitions), but by and large, we still functioned. Some parts of the organization (sales, first-tier support) got centralized, but all the stuff that required real expertise stayed together as "us". There were some organizational hiccups during this time, including the departure of the fantastic doc director who hired me, and then as a result the departures of several other members of the doc team. But the core held together. In the time that followed people came and went; the group was smaller but that aligned with evolving priorities. Things still worked. Meanwhile, R&D's dev teams had evolved into solid cross-functional teams of developers, QA engineers, and tech writers, and that was working well.

We went through a couple changes of doc manager, all promotions from within until the last. Until that last one, all the doc managers during my time there were also individual contributors; they didn't write a lot of doc because of other duties, but they took something, and thus had first-hand knowledge of how we worked. This manager didn't gain that experience but thought it wasn't a problem. I later had some unrelated issues with the manager, but other than that I was enjoying what I was doing and I soldiered on.

The leaders in R&D announced that we were switching to an agile process. Our cross-functional teams evolved into scrum teams, with some shuffling and adjustments to focus. I was asked to become scrum master of one of the teams I had been working with. (There's a story there, but I'll save it for another time.)

--

A year and a half ago, the company that owned us was bought. Read more…

Goodbyes are hard

The sound of a shovel-full of dirt hitting the top of a casket is raw, loud, disconcerting. I wasn't prepared for that.

I met Elaine when she started coming to my synagogue's Shabbat morning minyan something like 15 years ago. She was curious, perpetually cheerful, and perceptive. She cared about everyone around her and making sure people could participate in our community without barriers, long before a car accident and a resulting brain injury placed barriers before her. Her beautiful neshama (soul) shed light on us all.

She met her husband Noah and, to hear both of them tell it, it was an instant match. They both radiated joy at their wedding twelve years ago, and every time I saw them together. We played board games with them from time to time, and had many Shabbat meals and some Pesach seders together, and were all good friends.

Elaine died suddenly last week. She was 41. This is profoundly unfair. We've all lost a good friend and Noah is of course distraught. I hope that I and all his other friends can provide some measure of support, knowing nothing can repair the wound of losing his other half.

We gathered to remember her and say goodbye this morning. I took my turn with the shovel. And the sound of the dirt felt very final, even though her memory will live on in all of us and truly be a blessing.

Origins 2024

We went to Origins Game Fair last week and played a bunch of new-to-us games (and a couple familiar ones). Some notes (not full reviews):

Wednesday

  • Alhambra: The Red Palace (Queen Games): On your turn you can take money, buy tiles to expand your tableau, or take some special actions depending on conditions. I don't know which parts of this are the base game (which we've never played) versus the expansion. (There are soldiers who can be placed on your walls or sent to do tasks; that feels expansion-y.) Fun but not outstanding; I might look up the base game, which I've heard good things about.

  • Empire Builder "pot luck": We did this last year too. There's a train-gamers club that runs a bunch of games. For this, they showed up with game sets (higher-end custom builds, not the games we own) for many of the "crayon rail games" (Empire Builder, EuroRails, et al), and interested people self-organized into games of whichever ones they were interested in. We ended up in a three-player game of Iron Dragon. We all had some bad luck at various times and the final score was way more lopsided than the board positions would suggest, but I had fun. (But sigh, I was one turn away from delivering that load of dragons for 66 gold, which might be the highest payoff in the game.)

Thursday

  • Natural Chaos: two-player game with the feel of tic-tac-toe, rock-paper-scissors, and a capture/replace rule that adds complexity. Ok, not long, might not have a lot of replay potential.

  • Lacluck's Revenge (?): This was a vendor demo. Cooperative dungeon-crawl game, simple mechanics (for what we saw, anyway), maybe aimed for a younger crowd? We played a prototype; there's a Kickstarter.

  • Maglev Metro: We enjoyed this a lot and bought a copy. You're building a network, collecting resources (with preconditions), and building your "engine" to be able to take more/better actions. There are public goals and secret goals. The game is very nicely produced; in particular, each player has a stack of "track" tiles that are transparent other than one stripe, and they're all slightly offset from each other, so players can build in the same hex and you can still see everything. That's clever. Also, the boards where you're collecting pieces have slight indents so that you're not worrying about accidentally scattering things. Thoughtful physical production values, in other words.

  • Wingspan with an expansion (name unknown): We played Wingspan last year, bought it, and have played several games with friends. This session had an expansion that added a "wildcard" resource type and some special rules around it, also adding cards and replacing the game boards to account for that. I don't think the expansion carried its weight, but the session was fun. I seem destined to win Wingspan at Origins and mostly not at other times. (I won the game last year and also this one.) This game had some very nice component upgrades; I don't know if they're commercially available. There was a much better birdhouse, which sent us looking online and it turns out Etsy and others can solve that for us. (I was going to try to build my own, but I don't have the right tools so we'll probably just buy one.)

We attempted to have a late dinner at Barley's, a popular pub across the street from the convention center that gives away custom glasses every year, but they were very crowded and understaffed so we bailed.

Friday

Beer for brunch is fine, right? We were there at opening time, after a morning seminar, and that worked much better.

  • Seminar: Punish your players with landscape science: presented by a geology professor, a survey of how a variety of environment hazards "work" and how you might handle those effects as a GM. We talked about volcanoes, tsunamis, rip currents, a kind of landslide where a whole plateau moves (I forget what this is called), and several other things I don't now remember. Interesting food for thought; didn't take notes. Presenter's web site, includes a link to his book Landscapes for Writers and Game Masters: Building Authentic Natural Terrain into Imagined Worlds.

  • Gems of Iridescia: Fairly lightweight worker-placement game: mine gems of four different types to assemble the components to buy ("restore") artifacts; public and secret conditions for scoring victory points. Playable; has rough edges. The game is not out yet; the session was run by the designer.

  • Rolling Freight: Rail-building game with limited contracts and a random component. You have a pool of dice with different colors on the faces; those colors correspond to actions you can take and places you can build, so what you can do at any time depends on what you rolled this turn. You can buy a limited number of upgrades that either let you use your dice more effectively or give you more dice. In addition to building rail you're also trying to make deliveries, on as much of your own track as you can but you can use other players' track (and they get points for it). It feels like a good game in general (I'd need to play it a couple more times to judge it), but the board is difficult to see things on. Some board deficiencies might be things I could fix with the right stickers and Sharpies.

Saturday

  • Brass: Birmingham: Outstanding. We had ordered it online before leaving the convention. This is an industrial/economic game: you're trying to build a commerce network, producing goods in response to demand from other players and figuring out what to build to use your limited resources most effectively. Where/what you can build is governed by the cards in your hand. Turn order is set by spending: bigger spenders go last in the next turn.

  • Savage: A social game related to Werewolf/Mafia/etc but with better mechanics and a little randomness. Hidden-traitor games aren't my favorite, but this game seems to do it better than some others.

  • Dwarven Rails (2024): a lighter-weight network-building game with investment in rail companies. This is a "cube rail game", a term I had not heard before but maybe it's meaningful to my readers. You're building a network, but more importantly, you're building to increase the value of the companies you own stock in, so player alliances come and go. I ended up winning this by half-again the next highest player (who I thought was beating us all), and I don't entirely understand how that happened. The game has a lot of potential but also some issues. Our session was run by the designer, so feedback was received.

We also went to a two-hour seminar that was kind of rambly and was plagued by technical problems, so I'm not going to say more about that.

Sunday

  • Zhanguo: The First Empire: Complicated optimization game. It has a lot of room for strategy but was pretty overwhelming on a first play. (Having one teacher cover multiple tables was a tactical error on the part of the organizers, in my opinion.) Some of that might be "Sunday morning at the end of the convention" fatigue, some was definitely being the slowest player at my table, and a little was vision. Mostly, there were a lot of details to keep straight, and I admit to feeling relieved when it turned out the timeslot was an hour shorter than I thought it was (this will end soon). The game is very well-made physically except for one poor color choice in certain tiles.

Queen Games was running a limited special through the entire convention: present a coupon to get a (random) free game from their catalog. We've played and enjoyed several of their games, so this was interesting. People lined up for this before the hall opened and we didn't try (they limited the number each day), but on a whim, we stopped by Sunday morning on the way to our game, almost an hour after the hall opened, and there were only a couple people waiting and they still had games. They were down to their last ten and only had one option left, so we didn't get to see what the other games on offer were, but we now own a copy of Pirates, which looks light and cute.

Documentation for developers

Because of some organizational changes at my job, rumor has it that developers are going to be asked to contribute to writing technical documentation. Some developers on my scrum team were a little, err, concerned about that, so I wrote up some notes (and compiled some links) about our tools, conventions, and so on. I also included a philosophy section that is not specific to our product or company. I feel like I've written "tech writing basics" several times over my career; here's one more collection of quickly-compiled notes (far from complete).

--

I don't have time to develop a course in technical writing, but here are some thoughts as they occur to me.

Document the contract, not the implementation. You're deeply immersed in the implementation and might be tempted to pull content from the design spec. Instead, pull it from the functional spec. Think of the implementation the way you think of the private classes that probably make up most of it: that's for you (and you're free to change it), not for users to depend on. You expose interfaces in the code to protect the implementation; think of the doc as one of those external interfaces.

An awful lot of technical documentation that has probably frustrated you talks about "what" but not "why". We do need to describe the "what", like what all the parameters are, preconditions, interactions with other parameters/functions/etc, but ideally you wouldn't stop there. Put on the user's hat and ask: why would I want to use this? What problem does this solve? Good documentation starts from things the user is trying to do and then shows how to use (probably several) functions/statements/features/settings/etc together to do it. With luck, your functional spec starts there too, so you're not starting from scratch.

There are a few main types of documentation in most doc sets:

  • Reference pages: a complete description of each individual "thing" (class, function, command, etc) in a consistent layout with minimal distractions. Use outbound links for other supporting material.

  • Task doc: how to do a specific thing, usually a sequence of numbered steps. Keep it focused; the user is going to be going down the list probably typing (or cutting/pasting) the commands in the code blocks.

  • Troubleshooting: there isn't much of this in our doc, but some of our top-level categories end with a troubleshooting section. I build these up over time based on bugs that turned out to be pilot error, feedback from support, edge cases I notice in tests, and so on. Sometimes a functional spec calls out limitations up front and I add a troubleshooting section that approaches that limitation from the other side.

  • "Guide" doc: a mix of overviews, conceptual doc, and scenarios. This doc usually covers the "golden path" and should not try to be exhaustive (that's what the reference doc is for). You'll see some older doc in (location) that mostly repeats the reference pages without adding much; don't emulate that.

(Some doc "frameworks", like DITA, slice up the world a little differently: reference, task, concept. I naturally think my division is a little more on-point for the kind of doc we're writing, but it's just one person's opinion.)

Good examples are gold. Bad examples are tedious. One person's good is another person's tedious, but asking the question is the first step: what purpose does this example serve? Examples don't need to be exhaustive like unit tests; examples illustrate, and they show clearly how to do tricky things, but you don't need the combinatoric explosion of all possible arguments and parameter values in the doc. Examples, like doc, should be as concise as possible while still accomplishing the primary purpose.

When writing examples, it's helpful to users if you can attach some meaning - instead of an ML function operating on columns c1, c2, and c3 in table t1, can you imagine a scenario where people would actually use it and mock it up instead? Particularly for long or multi-step examples, it's easier if readers can hook onto some semantic hints, even small ones. This helps with the "wait, which one was c2 again?" backtracking that happens when reading subsequent explanation or steps. Your examples might not be completely realistic, but try for some "realism flavor".

Scrum-master philosophy

I've mentored a few other scrum masters and am writing down some of my so-called sage advice for coworkers. This part isn't specific to our organization, so I'm posting it here and not just behind a corporate VPN.

--

Philosophy

The scrum master and product owner should work closely together and ideally be able to complete each other's sentences stand in for each other. As scrum master I'm not the one who makes decisions about priorities and technical direction, but I should know enough about everything we're doing to ask questions and prod gently. The SM and PO are partners and each strengthens the other. Have 1:1 conversations with your PO alongside the team discussions.

Asking questions is a great, non-threatening way to prompt conversations. Think Socrates.

According to Agile (not just SAFe, the specific framework we use), part of the scrum master's job is to remove roadblocks. In my opinion, a key aspect of this is a style of "servant leadership" -- if there are things that "anybody" can do and other things that require expertise, then to the extent possible, as scrum master I should take the former so that other team members can do the things that only they can do. This is why I do easy server backports, participate in PR reviews, and help with functional testing, none of which fit into my official job description.

To an outside observer a scrum master might look a lot like a project manager, but you're embedded in the team, not coordinating things from outside. You do need to do the management stuff, but don't let it keep you from being part of the team too. You know the work, you know the people, and you know how to talk with the latter about the former.

Unforced failures: employee motivation

My employer does a thing where, for round-number anniversaries, they collect congratulatory messages from your coworkers and then deliver an online compilation on the day. Commenters are encouraged (I know from having been solicited) to share praise, stories, and other positive stuff. It's a low-cost, low-effort (for them) way of sending warm fuzzies. If they didn't do this at all, no one would miss it. Since they do do it, naturally people expect it to be a positive experience for the recipient. (I assume that comments are moderated.)

When my fifth anniversary was approaching, the way the system worked is that some automated system sent a link to the recipient's manager several weeks in advance, with instructions to forward the link to the recipient's coworkers and ask people to participate. (Everybody with the link could see what comments had been left so far.) I've responded to a number of these over the years and have seen compilations with messages from across the organization. When I got mine, it had... a generic message from an HR person I didn't know, a brief message from my manager, and nice messages from two other members of my immediate (doc) team. (I later learned that some other team members hadn't been notified in time.) I was at the time working with two or three cross-functional teams of developers, QA folks, and product managers, but my manager didn't send it to any of them. Eh, whatever, I guess?

We've been acquired since then so the systems have changed. I recently got an automated message about a coworker's upcoming fifth anniversary, as opposed to a message from a manager. I do not know if the manager was asked to choose recipients, or if the system is somehow choosing based on reporting relationships, or what. I've only seen one invitation under the new system so far. As with the older system, anybody with the link can see the comments.

Yesterday was my tenth anniversary, and I had email this morning with a link. I looked and found...a generic message from the CEO. I looked around the site a bit, thinking other comments must be in a different place, but I didn't find any. I then thought to look at the link for that coworker's upcoming anniversary, and saw the same CEO message and my comment.

So, um, nobody commented? Nobody at all, not even my manager? And their system didn't detect that and, you know, send a nag message to the manager and if necessary delay sharing the link with me?

So many avoidable failures, starting with: don't do stuff like this if you aren't set up to make it a positive experience. This is worse than doing nothing. Not only is this not motivational, but it's actually demotivational. The message it sends is: "we care about looking like we care".

(No, I do not plan to be here for the fifteenth to see if they've gotten their act together.)

Garden lineup

I just finished putting seedlings in containers. Let's see what survives. This year I learned about companion plants so I'm giving that a try in the big pots. And I also bought some liquid plant food to see if that helps with the bounty.

The pickings for cucumbers were pretty slim and mostly marked "thrives in ground". I found one hybrid bush that said it's suitable for containers. The seedling looks like it's struggling a bit, but we'll see what happens with room and food. Meanwhile, I'll keep looking for another.

I'm trying tomatoes again despite the loss to critters last year. Apparently basil is a good companion plant for tomatoes: the core of Caprese salad in one pot! (But just in case, I also have basil in a separate pot.)

Leaving the nest

Four weeks ago I had a robin's nest with three eggs on a rafter outside my back door. For the last couple weeks I've caught occasional glimpses of beaks or even heads over the edge of the nest. (The nest is above eye level.) The adult birds have been very adamant when we enter or leave, even though I try to do that gently and non-threateningly.

In the last few days I've seen young nestlings standing on the edge of the nest and even on the rafter. I've watched them flap their wings vigorously without getting lift yet.

Yesterday, by virtue of lucky timing -- looking out the window at just the right times -- I got to see two of them fledge. Neat! This morning there was no activity around the nest so I got the ladder and held my phone up, aiming down, to check on the state of the nest -- empty. So number three seems to have figured it out too.

It's been fun watching them grow and learn to use their wings, and watching the family (or the parts I could see at that angle) for the last few weeks. Simple serendipitous joys of urban life. If it happens again I need to figure out how to do a nest cam.

Ya'aleh v'yavo hit me hard during Pesach

During the festivals and some other special times throughout the year, we add or adjust prayers to reflect these special times. This includes specifying the day -- we call Pesach by name and also refer to it as z'man cheruteinu, the season of our freedom.

One of the additions is a prayer called Ya'aleh v'yavo, where we ask for specific kindnesses from the Almighty. And so it was that during Pesach, z'man cheruteinu, I found myself saying roughly:

Our God and God of our fathers, show us your care and concern. Remember our ancestors, recall your anointed, protect Yerushalayim your holy city, and exalt all your people Yisrael with life and well-being, contentment and peace, on this Festival of Matzot. Grant us life and blessing, and remember us for good. Recall your promise of mercy and redemption. [...]

There I was praying for life and prosperity and well-being in the season of our freedom, and even more than what has become usual since October 7, the discordance hit me hard. We who can stand in synagogues and pray these words have life and well-being and, I hope, some measure of contentment and peace, unlike our fellow Jews who for over 200 days now have faced cruelty rivaling that of Paro in Mitzrayim, and while many in the world (and close to home) celebrate the cruelty and call for more suffering and pain and pogroms. I knew all of that in my head and we've all seen it play out for months, and then there I was, praying Ya'aleh v'yavo in freedom, and... bam. This year it is not about my freedom when (as the haggadah tells us) I went out of Egypt's cruel oppression. This year it is about the victims of today's evil oppressors. I pray that the next time I say these words, it will be in celebration of everyone's freedom from the cruel reign of Hamas.

New neighbor

A nest appeared just outside my back door a couple weeks ago. I saw an occupant early on, and then not for a long time, so I wondered if the nest were abandoned. Earlier this week I started seeing a bird in it again; I've tried to be careful in coming and going but she always flies away. This happened in the same spot several years ago and we eventually had a family of young robins, so I'm hopeful.

I managed to snap a picture of mom earlier today:

Image without description

Later I saw her fly away, startled by some small sound I guess, so I quickly confirmed my suspicion, holding a camera up at arm's length and shooting blind:

3 blue eggs

Yay, incipient chicks!