Blog: Work

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.


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…

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.



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.)

Glassdoor updates

Some updates on Glassdoor's privacy violations:

Use to request deletion of your data. Deactivating your account doesn't delete data. This might not either (no way to verify), but it's the strongest request you can make.

Media coverage: Ars Technica: Users ditch Glassdoor, stunned by site adding real names without consent, Wired: Glassdoor wants to know your real name. The Ars story is more detailed.

It seems that Glassdoor updated its terms of use on February 17, 2024. I did not receive email notification (my last TOS update from them was December 2022). Some salient bits from the current version:

We may update your Profile with information we obtain from third parties. We may also use personal data you provide to us via your resume(s) or our other services. You can read more about how we collect and process your data in our Privacy Policy.

I never provided a resume. I never typed my name into their site, nor did I use a social-media or Google identity. I created the account with an email address (~10 years ago). That part about "obtain from third parties" means they can try to match you up with LinkedIn, use your email headers if you should ever send them email, try to reconcile your account with Indeed if you're there (the same company owns both Glassdoor and Indeed), and whatever else they come up with.

Also, sometimes the information they add is incorrect. From Ars Technica:

As Monica's blog spread widely online, another Glassdoor user, Josh Simmons, commented to confirm that Glassdoor had "already auto-populated details" on his account, too. But instead of correcting Simmons' information, Glassdoor seemed to be adding mistakes to his profile.

Simmons, who requested to use his real name and share his employer information, is a managing director of Foundation. He discovered that Glassdoor had not only messed up his employer's name but also claimed that he was based in London, while he is actually located in California.

"It was bizarre, because I had never provided that information, and it was a somewhat incoherent mix of details," Simmons told Ars.

Back to the terms of use:

We may attempt to verify your employment history or status through various methods, including third party integrations or services. We may also utilize signals we receive from your current or former employer. Glassdoor is not responsible to you or any third party if we are unable to or inaccurately verify your employment history or status.

I don't know what "we may utilize signals we receive from your employer" means, but it sure sounds like "we might ask your employer if you work there", because your employer knowing you've posted Glassdoor reviews to prompt that question would be a "you" problem, not a "Glassdoor" problem.

(This information is repeated in the privacy policy.)

In order to provide you with access to features across our services, we may create and link different services’ accounts for you.

This is the part about them automatically creating a Fishbowl (social media) account on your behalf, without you explicitly doing anything and apparently without direct notification.

A portion of your Profile on our community and conversation services (e.g., Fishbowl and community and conversation features across our services) is always public. Therefore, your profile picture, company name, title, and other general information (but not including your semi-/anonymous Content submissions) will be visible to the public and available via search.. Content submitted with semi-/anonymous identifiers such as your company name or job title is not associated with the publicly-visible portion of your Profile.

So they added my name to my Glassdoor profile without consent, then propagated that to Fishbowl, and the Fishbowl profile was public?!

Glassdoor responded to Ars:

"We vigorously defend our users’ right to anonymous free speech and will appear in court to oppose and defeat requests for user information," Glassdoor's spokesperson said. "In fact, courts have almost always ruled in favor of Glassdoor and its users when we’ve fought to protect their anonymity. With the addition of Fishbowl’s community features to Glassdoor, our commitment to user privacy remains ironclad, and we will continue to defend our users from employers who seek to unmask their identity."

They "vigorously defend" privacy, yet they collect and store information that violates privacy. Also, note that what they're saying is that they'll defend outside requests for data ("almost" always successfully), but they say nothing about their own proactive use of that data -- like selling it to employers.

That data-deletion link once again:

Time to delete your Glassdoor account

Recently I contacted Glassdoor for an account-related issue. This led to them sending me email that I had to respond to. Big mistake.

The TL;DR is: Glassdoor now requires your real name and will add it to older accounts without your consent if they learn it, and your only option is to delete your account. They do not care that this puts people at risk with their employers. They do not care that this seems to run counter to their own data-privacy policies. Read more…

Another bad user experience

My employer got bought (again) about a year ago, so we're being moved onto a new benefits setup as of January 1. This means new health insurance (with new prices, sigh...). We were told we'd get our ID cards in December. I have an appointment in early January that would be a pain to reschedule, so I've been watching for these.

Today I received physical mail, but instead of cards, it contained a piece of paper telling me my plan ID # and a URL where I can request cards or print my own.

They sent me paper to tell me how to request paper, instead of just sending the actual paper I needed.

After creating an account (another set of hoops, elided) I saved PDF copies, but I also asked for physical cards because paper probably won't stay in good shape in a wallet for a year. But this was unnecessarily complicated. I also hit a stupid limit: you can make one request per day, but both my medical and dental insurance are now with this carrier, that's two cards, and there was no way to request all cards. I requested the first, which was apparently successful, and when I requested the second I was told I couldn't.

The letter I got suggested I could use "digital cards", meaning download an image on my phone and skip the paper entirely, to "save space in my wallet" (not a concern, since I'm replacing this year's cards!). But my healthcare providers always want to hold the cards, sometimes keeping them for a while so they can do data entry at their convenience during my visit, and I'm not handing over my phone for that. My phone stays with me or, at worst, within my sight and otherwise locked. So paper it is.

I don't know if I'm abnormal or the insurance provider didn't think through their security model (maybe both). They sure didn't think through their model of what's convenient for users or lower-waste for the planet. By the time this is done they will, it appears, have sent me three separate pieces of physical mail.

Scrum-master hack

"Scaled agile" ("SAFe") scrum-master hack:

Our sprints are numbered within cycles (5.1, 5.2...). I just made a sprint named because I need a holding pen for not-yet-scheduled plans in this cycle (versus the "planned eventually" backlog), and I don't care if this is the "SAFe way" because I just need it to work for our team. I'll delete the fake sprint when it's empty, but if something isn't on the dashboard it might as well not exist and this is the only Jira hammer I have. I'm not sorry. It's expedient.

"Scaled agile" (aka "SAFe"; cutesy abbreviations are all the rage) isn't really agile, but it's the process we've been directed to use. I told them when they asked me to be a scrum master that I will be expedient and will prioritize serving the needs of my scrum team over the holy writ from the vendors selling this stuff, and if they have a problem with my approach they should get someone else. They didn't, so...

I'm delighted that several newer scrum masters have come to me for mentoring. Apparently I have a rep for getting stuff done. :-)

Standup meeting

Product manager: this resolved bug needs a severity.

Me (scrum master): would the product owner (that's a scrum role) and the developer who fixed it please handle that?

Developer: I am the product owner.

Me: I know. I assume it won't take the two of you(r roles) long to reach consensus.

Am I doing it right? :-)

Office check-in

Before the pandemic, I went to the office every day, as one does. Our office manager did what he could to make it an ok environment, but it has the usual pathologies. Pandemic-induced working from home has been good for me in oh so many ways. I'm fortunate to be at a point in my career where I am quite comfortable telling my employer "I really do insist". (There's some pressure, mild so far.) I'll go to the office if there's a specific reason to, like the group outing we had a few months ago, but most of the people I work with aren't local, so going to the office is social, not productive.

On the day of that outing, I learned -- via a coworker finding out the hard way -- that corporate security disables badges that haven't been used in 90 days. That makes sense, though doing it silently isn't so great. Fortunately for me, I last changed my domain password around the time of that outing, so the "time to change your password" reminder serves double duty.

A few days ago I changed my password, and today I went to the office to wave a badge at a sensor. While I was there I cleared out the last of my personal belongings; demonstrably, I no longer need to keep an umbrella or a spare USB charging cable in my desk drawer there.