Blog: Tech

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.

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…

Pobox in the 21st century

I've been using pobox.com since (checks...) 1996, when I needed to change email addresses and wanted to avert the hassle of getting updates pushed out the next time I had to do that. Pobox does two things: it gives me an email address that I can redirect wherever I want, and it gives me URL forwarding: a Pobox account comes with the ability to redirect http://www.pobox.com/~your-name to wherever you want.

I got email from Pobox today announcing that URL redirection will be discontinued in a couple months:

[...] Pobox alias URLs once served the same purpose as Pobox email aliases: you could get one URL and have it follow you as your web page moved. Over time, though, personal domains have taken over this use case, and Pobox’s URL redirection service is almost entirely unused. Upcoming changes to our web interface make this feature much harder to continue offering, and we have decided to retire it.

Your account’s URL is one of the few that has seen traffic in the last six months. Maybe that’s a fluke, and you’ve stopped using this URL, and it redirects to some long-abandoned page you owned in the 1990s. On the other hand, you might still be using this URL. If that’s the case, you should begin updating links to your Pobox URL and instead link directly to the target resource, or some other redirection service. [...]

As it happens, I am using that URL, and updating links kind of depends on knowing where the links are. (I mean, updating my own links is easy, but that's not why one uses redirection.) I use the domain I acquired in 2017 for all new stuff, and I've been migrating old stuff intermittently. But I didn't finish and cut over, because there are links to my old SCA stuff (in particular) all over the place out there, and I couldn't figure out how to cleanly make all the URLs work -- Pobox gives me one top-level redirect, but if I can't exactly preserve the structure under that, I'm into the realm of individual redirects and that's a big hassle.

Well ok, then -- Pobox is forcing my hand (and I don't really blame them if usage is that low), so I'll just rip that band-aid off and not worry about making the soon-to-be-dead URLs work on the new site. I also hit the Wayback Machine and archive.today with some pages I know are linked, and I asked Pobox if they could give me referrer logs so I can see if there's anyone I ought to notify. Beyond that, I'll just have to assume that search engines will eventually index the new locations and anyone who really cares will search.

Tonight I migrated my SCA pages, which are mainly the page (and many pictures) for the Pennsic house, since Greg Lindahl is already hosting most of my music (and Joy & Jealousy). I also had a bunch of stuff related to the Board crisis of 1994; rather than port all the individual pages, I archived it online and then dropped a ZIP file on my site. It was 30 years ago; I suspect very few people are interested, and those who are won't mind downloading the bundle.

My Pobox account next renews in 2029. I have email through my domain but, again, a lot of people use my Pobox address and updates are hard. But perhaps in the next five years I should attempt to put that change in place, because who knows if email forwarding will go the way of URL redirection by then?

Breaking into a Mac?

Dear brain trust,

My father had a laptop, an old MacBook. My mother would like to know what's on it. It's password-protected. I've been unable to guess the password, even knowing some of his other passwords and some patterns he used.

I have the passwords to his two desktop computers (iMacs), but also can't get in via network share (access denied). I have his cell phone, which should let me get into his iCloud account (that's the second factor). I have the impression that none of that will help.

Is there any way I can override the laptop's password and get in anyway? Or connect an external drive and make a copy somehow? I'm willing to take the laptop and a copy of the death certificate to an Apple store, except that I don't know if it's technically possible to get in (without damaging the contents, which is the whole point of the operation). I mean, we'd all like security to actually be secure, so this shouldn't be easy, but is there something between "easy" and "impossible" that I can try?

The laptop is at my mom's house, so I can't test things immediately, but I'm looking for any clues that could help on my next visit.

Swiss-cheese security

Cory Doctorow's How I got scammed was a fascinating read. Phishing has gotten more sophisticated, but also, even people whose security practices are way above the norm can get hit when the stars (mis)align just so.

There's a name for this in security circles: "Swiss-cheese security." Imagine multiple slices of Swiss cheese all stacked up, the holes in one slice blocked by the slice below it. All the slices move around and every now and again, a hole opens up that goes all the way through the stack. Zap!

The fraudster who tricked me out of my credit card number had Swiss cheese security on his side. Yes, he spoofed my bank's caller ID, but that wouldn't have been enough to fool me if I hadn't been on vacation, having just used a pair of dodgy ATMs, in a hurry and distracted. If the 737 Max disaster hadn't happened that day and I'd had more time at the gate, I'd have called my bank back. If my bank didn't use a slightly crappy outsource/out-of-hours fraud center that I'd already had sub-par experiences with. If, if, if. [...]

The following Tuesday, I called my bank and spoke to their head of risk-management. I went through everything I'd figured out about the fraudsters, and she told me that credit unions across America were being hit by this scam, by fraudsters who somehow knew CU customers' phone numbers and names, and which CU they banked at. This was key: my phone number is a reasonably well-kept secret. You can get it by spending money with Equifax or another nonconsensual doxing giant, but you can't just google it or get it at any of the free services. The fact that the fraudsters knew where I banked, knew my name, and had my phone number had really caused me to let down my guard.

Years ago, I got a call on a weekend from someone claiming to be from my credit card and was just plausible enough for me to not hang up. (Also a claimed fraud alert.) But I got suspicious when the caller started asking me for private information and then claimed it was necessary to authenticate me (at my own phone number). So I said "I also need to authenticate you; what's my mother's maiden name?" Oh no, the caller said, we can't give you that information... but with all the data breaches we've seen, that technique is no longer safe. The phisher might have my mother's maiden name [1]. Doctorow's phisher had his unpublished phone number. Secrets aren't.

[1] Helpful tip: don't use the actual answers for security questions that people might be able to research or guess. As far as your bank is concerned, your mother's maiden name can be QjFVa6ufeqr_7.

Personal database with web front end 101?

I've been using RateBeer to track beers I've tasted and how much I liked them. This is helpful to pull up on a phone in a restaurant or store. But it relies on their database; if they haven't heard of a beer (and I don't want to do very cumbersome editing to add it on the fly), I can't rate it. Untapped seems to have a larger database but a terrible mobile site.

Fundamentally, this is the wrong approach for me anyway. Sites like RateBeer and Untapped exist to collect and aggregate user-contributed content. I don't care about that. I'm not interested in "social beer". I just want to keep track of things I've tried. And this isn't really just about beer; in days of yore when I bought more books on paper, I wanted to be able to look up what I already own while standing in a bookstore, but GoodReads is not really the interface for that. Similarly, keeping track of board games I like (and variants) is not really a job for BoardGameGeek.

What I need is my own private little database, with a web front end to support both queries (searches) and data entry. I'm the only user, so I don't need anything fancy. (Web, not app, because while I'll do some data entry on the phone, anything non-trivial is going to be done on a computer with a real keyboard.)

This sure feels like a solved problem, but I'm not quite sure what to search for. (Or rather, my searches are leading me to pages like "how to use .NET to build your web form".) My web hosting comes with CPanel links to set up both MySQL and Postgres databases. I think I know the basics of raw HTML forms but I don't yet know how to hook one up to a running database, nor how to access-protect it. I'm comfortable with the SQL to create and query the tables, and while every database is a little different on this I assume I can figure out data import from CSV.

Or maybe I should be looking for something hosted, like Google Sheets but for an actual database. (I've tried importing this data into Google Sheets. Using that on my phone is pretty terrible and it doesn't really support search anyway.) So long as I can export data from someone else's service, I don't need to self-host. But if self-hosting is easy I'd prefer that.

Out of curiosity I asked ChatGPT, and it gave me some PHP with a username and password baked in and a suggestion to do better security. The code doesn't do quite what it said it would do (based on inspection), but it's broadly plausible and ChatGPT even pointed out the problems with security, input sanitation, and validation.

Any advice from my readers?

And after, there is tech support

My mother is not computer-savvy, and when she's ready I'll help her sort out my father's computer stuff and (I hope) break into his account so we can sort out whatever household stuff he was managing online (like bill payments). She has "an old password" written down; here's hoping that helps.

She mentioned, in passing, that she'll contact their cell carrier to drop his line -- no sense continuing to pay for a second phone, after all.

Do I need to prevent her from doing that until we determine whether he was using 2FA for anything? I haven't figured out the right search queries that will cut through what you should do in advance lest you lose your phone. Like, I don't know where or if he was using 2FA, so I can't just go in and set alternate recovery addresses or something. The point is to be able to get into those accounts later, when my mom is ready. Does she need to keep paying for cell service so that phone number will be able to receive texts, or is there some other way to handle that? Should I go with her when she visits the cell provider (yes she was going to go to a store and do that in person)?

Anybody among my readers navigated this before?

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.