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.

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

Glassdoor updates

Some updates on Glassdoor's privacy violations:

Use https://help.glassdoor.com/s/privacyrequest?language=en_US 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 Matrix.org 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: https://help.glassdoor.com/s/privacyrequest?language=en_US.

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 5.rest 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.

Employers, how many of those vacation days are real?

When you're considering a new job, one of the things you'll find out as part of the package is how much vacation (or PTO, "paid time off") the offer includes. The US doesn't do as well in this regard as some other parts of the world. In tech, you can probably expect two to three weeks of vacation days per year plus six or seven designated civil holidays. In some companies, after you've been there several years you earn more days per year. (At my current company, after five full years I started earning one extra day per year.)

Next time I consider a new job, I have to remember to ask not only how much PTO is included but how much of that is actually mine. It's not mine if the company says I get X days but that I have to allocate some of them for Christmas week "because we all need time then to be with our families". That would be patronizing and presumptuous even if Christmas were my holiday! It's not, so that makes it even worse.

It's fine if an employer says "we're closed that week for business reasons". Sometimes companies do that. But in that case, they should either grant those days (as if they were civil holidays) or reduce the PTO claims in their job ads and HR policies. I use several days per year for my holidays, ones they don't grant, plus (in non-pandemic years) actual vacations that I choose. I would like employers to tell me the number of days I really have, the number that are my choice.

When I joined my current company I was told how many PTO days I get per year. Later, they started declaring mandatory shutdowns for Christmas week. I can use my vacation days or take the days unpaid.

Retracting vacation days, which is what they do when they say I can't use them freely any more, is akin to cutting salary (as is saying "then take it unpaid if you didn't save vacation days"). Employers, be honest about that: you're reducing my compensation. Do not pretend you're doing it for my well-being, for my family time, for my holiday -- you're not. How valued am I really, if you reduce my compensation so casually?

I've always found the last week of December to be a great time to get work done; I can focus on things that keep getting pushed off or interrupted, because there are few or no meetings and other interruptions. Meanwhile, I can use those days for my holidays. Everybody wins.

Companies should actually consider giving top employees more vacation days, rather than only the tenure-based allocation. When someone consistently performs above the norm, then not only should you reward that, but you're still ahead of the norm if the person takes that time off! Employers, please start considering PTO increases as part of the mix that includes salary increases, bonuses, and assorted perks that people use inconsistently.