The new podcast “This is Uncomfortable” had an episode about crying in the workplace. I don’t have a lot to say about it, other than it’s a good story. But I wanted to go on record as saying that I cry at work.
Sometimes work is overwhelming. Sometimes my personal life leaves me on edge. Sometimes I read a moving article.
Sometimes I cry. It’s okay to feel things.
Earlier this year, I attended a pitch night at my local coworking space. One of the teams that presented is working on a product to help prevent driving while drowsy. It’s a noble goal — drowsy driving can be as dangerous as drunk driving. Like drunk driving, people aren’t very good at self-evaluating their fitness to drive when they’re sleepy.
But as they talked, I sat there going “no. What are you doing?” They talked about learning who the driver is and establishing a baseline of their attentiveness to measure their drowsiness. All kinds of cool whiz-bang stuff. And maybe someday they’ll add some haptic feedback to the steering wheel.
I suggested that they target diabetics as a first market. Hypoglycemia is dangerous, too, and it’s an easily-defined audience, which helps in initial go-to-market efforts. When I talked to them after their presentation, they started talking about maybe adding blood sugar sensors.
No. Just no. I asked them if they’d considered what storing data might mean. It creates a liability for the driver in case of an accident. It could be used by insurance companies to change rates. It could be compromised and used for something else.
Using the latest tech is neat, but only when it makes sense. And sometimes, the more you add, the worse things get.
On Monday, The Perl Conference’s Standards of Conduct Committee published an incident report. In a talk at the conference, a speaker deadnamed and misgendered a member of the community. As a result, they took down the YouTube video of that talk.
The speaker in question happens to be a keynote speaker at PerlCon. The PerlCon organizers wrote a pretty awful post (that they have since edited) that essentially dismissed the concerns of the transgender members of the Perl community. They went on to mock the pain that deadnaming causes.
I did not think to save their post in the Wayback Machine before they edited it down to a brief and meaningless statement. “We are preparing a great conference and do not want to break the festival and trash our year-long hard work we did for preparing the confernece, the program and the entertainment program.”
What they don’t say is “we value the marginalized members of our community.” And they make that very clear. Editing out the insulting part of their post does not ,mean much, as VM Brasseur pointed out.
If you value an inclusive community, you have to stand up for the marginalized members when they are excluded. If you don’t, you make it very clear that you’re only giving lip service to the idea. As it is, the PerlCon organizers don’t even apologize. They’re more concerned about the bad publicity than the bad effect on the community.
What does it mean to do your best? I was recently talking to a friend about this. She’s a single mother of four and at the time of the conversation was working part time while she completed her bachelors degree. She was upset because she felt like she wasn’t doing the best she could on a particular paper. This bothered her because she’s someone who always tries to do her best.
I said she still was. Just because she could have, in isolation, written a better paper, she’s still doing her best in aggregate. That’s one of the most important things I learned in grad school: how to let some things slide while keeping the overall effort.
Despite what years of motivational talks (and a poem called “Good Enough is Neither” that was drilled into us in ninth grade) have told me, sometimes good enough is good enough. It’s all a balancing act. Part of being an adult is knowing how to strike the balance between all of the things you have and want to do.
For folks with a singular pursuit, perhaps they can focus all of their energy on doing their absolute best in a single thing. For most of us, life doesn’t work that way. Your job isn’t one thing, it’s a collection of things that you do. This is even more true for your family and friends. Sometimes you have to do less than your best at one thing in order to do well enough somewhere else.
I tend to view “doing my best” not as something that happens on a single task, but as a reflection of my effort in the aggregate. I think that’s a healthier approach.
Last week, Fedora contributors proposed to change the meaning of “python” from “python2” to “python3” starting with Fedora 31. This makes sense in the context of Python 2’s upcoming demise. But some feedback on the mailing list, including mine, wonders why we’re perpetuating it.
Should there also be no “pip”, no “pytest”, no “pylint”, … command? I would say “yes”. Admittedly, it’s avoiding future pain in exchange for some current pain. But we’re already dealing with a disruption, so why enable the same issues when it’s time for Python 4?
This is bigger than Python, though. If you’re following semantic versioning, I argue that you should name your interpreters and any ecosystem executables with the major version name. Unless you’re promising to always maintain backward compatibility (or to just stop working on the project), you’re eventually setting your users up for pain.
What about non-programming languages? This is probably good advice for anything with a client-server model (e.g. databases). Or anything else where the command is separated from other components of the ecosystem. You could extend this to any executable or script that may be called by another. That’s not wrong, but there’s probably a reasonable line to draw somewhere.
Wherever you draw the line, doing it from the beginning makes life easier when the new, incompatible version comes out.
What have I been writing when I haven’t been writing here?
Stuff I wrote
Stuff I curated
Amazon famously has meeting attendees read documents at the beginning of the meeting. It seems to work well for them (I’m not sure that’s the secret sauce, but that’s for another day). Tech exec Jason Crawford recently had a Twitter thread promoting this concept.
He got some disagreement on this, including from my friend Julia who considered it “inaccessible and exclusionary”.
Her arguments are right on and sufficient on their own. But there’s a broader point too: this is solving the wrong problem.
[ed note: The previous paragraph does not sufficiently express my intent. The exclusionary effect that Julia points out are reason enough to not engage in this practice. Full stop. My point about “solving the wrong problem” are more along the lines of “even if it weren’t exclusionary, here’s why you shouldn’t do it.” Thanks to Ruth for the comment that calls this out.]
Is your document too long for people to understand and digest? Fix that! Identify people who can act as editors that can help others within your organization write better documents. Or better yet, pay for writing training for your employees. It costs money, but it produces real (but hard-to-quantify) savings. Not only will you save time by having more understandable documents, but you may even have better ideas.
Are people not reading it because they’re too busy or don’t care? Fix that! Maybe it’s irrelevant to the person; that’s an indication that they don’t need to be invited to the meeting anyway. Or maybe they’re overworked, or mis-worked. That’s a management problem that will manifest elsewhere. Or maybe they’re just not doing it. Again, that’s a management problem — if that doesn’t show up in their performance evaluation, then you’re showing that it’s not actually important to you.
Jason suggests scheduling a 90 minute meeting if the document takes 30 minutes to read. That’s a waste of 30 minutes. Yes people should absolutely read the document. But they should also have the flexibility to do it when it makes sense to them. Maybe they have a train ride home that they’d rather do reading on. Maybe they like to block out time around their other meetings. It’s not valuing their time to decide when they get to read the document.
He also says it avoids “negotiation” about how soon in advance a document should be sent. This is a cultural norm that you can set. All of this comes down to a shortcut to avoid the hard work of setting a culture that gives people flexibility while still holding them accountable.
Hopefully the answer isn’t “none”! Let’s assume you’re writing documentation because you’re a wonderful person. Is it a comprehensive discussion of all the features in your software? Good…sort of.
There’s a place for in-depth, comprehensive reference documentation. And that place is often “over there in the corner collecting dust until someone really needs it.” By and large, people are going to need smaller, more task-focused docs. It’s a difference between reference guides and user guides. Or as I like to think of it: “what could I do?” versus “what should I do?” These are not the same documents.
“What could I do?” docs should be chock-full of facts that are easy to discover when you know what you’re looking for. They don’t have opinions, they just list facts. You go to them for an answer to a very specific question that has a correct answer.
“What should I do?” docs should be opinionated. “So you want to do X? The best way to do that is Y, Z.” They’re focused on accomplishing some use case that the reader can probably describe in human language, but might not know how to do technically.
A great example of “What should I do?” docs is the tldr project. Unlike man pages, which are generally reference docs, tldr-pages focus on use cases.
When I was more active in the HTCondor project, I often dreamed (sometimes literally) of writing a book about administering HTCondor pools. The developers had a great reference manual, but it often lacked the more opinionated “here’s what you should do and why.” It’s something we should all consider when we write documentation.
Gatekeepers are a problem in communities. They decide — often arbitrarily — who can and cannot be members of a community. Are you a true Scotsman? A gatekeeper will tell you. And if there’s something they don’t like about you, or they’re feeling particularly ornery, they’ll keep you away from the community.
Gatekeeping is a problem in open source communities. More experienced (or just louder) contributors set a bar that new contributors cannot meet. This is bad for folks who want to contribute to the project, and it’s bad for the project’s sustainability.
A recent Opensource.com article asked “What is a Linux user?“. In the initial version, it left open the possibility that if you’ve only used a Linux desktop that doesn’t require a ton of tinkering, then you’re not a real Linux user. Fortunately, the comments called this out quickly. And the author, to his credit, did not hold this view. He quickly updated the article.
The revised article does a much better job of closing the door on gatekeeping, but I would rather it have never run at all. By engaging in debate on the question, you give it validity. It’s best to deal with gatekeeping by not even acknowledging that the question is valid.
Every once in a while, someone suggests writing laws like code. Bills are pull requests. You can easily see diffs from previous versions. It’s an appealing idea.
But sometimes I think about how political structures resemble code. Specifically, the U.S. Constitution reminds me of most of the code I write: it’s mostly happy path and there’s not a lot of error checking. They both assume good actors all around.
Just as Madison et al did not consider that a presidential candidate might receive material support from a foreign power and that large portions of the Congress might choose to turn a blind eye to it, I don’t really think about how a bad actor might use code I write.
Of course, I mostly write code for my own use. And the Constitution isn’t workable if it covers great detail. But a little more exception handling and testing is probably good for both of us.