In short, you can read this blog three different ways:

1. Via a web browser @ https://famularo.org
2. Via RSS in the reader of your choice @ https://famularo.org/rss/
3. Via social web client of your choice
   • ActivityPub (Mastodon, many others): @blog@famularo.org
   • Bluesky: @blog.famularo.org.ap.brid.gy

Will this cause me to post more stuff? Probably not 😅

Every so many years I look at my blog or personal website and get that urge to tinker with it and try something new. And that time was recently, as I've moved my blog from Svbtle to Jekyll hosted on GitHub Pages. It all started when I tried to update Svbtle to use the newer Google Analytics setup, but found it was not supported. From that problem, I got squirreled and ended up moving to a new blog host.

Why Jekyll?

Jekyll may not be the hot new thing, and as I get older—I mean more experienced—I realize that the latest thing isn't always best in the long term. Instead of basing things on a technology, I'm basing them on a format: Markdown.

Svbtle already used Markdown, so that part was (mostly) painless. I did end up using svbtle-jekyll, a small Python tool that extracts Svbtle posts and puts them in Jeykll format (from what I can tell is kramdown + a header). svbtle-jekyll required a few tweaks to get it to read the HTML correctly (it is 7 years old—it almost worked out-of-the-box!)

Now that my blog posts are in Markdown and stored in a git repo I own, it should be easy to move them elsewhere if—and when—I decide to move to a new platform.

Jekyll also made it easy to keep the same URLs for my posts so I don't have to mess with HTTP 301 redirects.

Theming

In looking for Jekyll themes, I quickly found Minimal Mistakes, which is a very popular—if not most popular—theme for Jekyll. Once I made it through setup and dependencies, I was off and running. So now I am running on a static website that is free to host and doesn't look half bad.

What's next?

Am I going to (re)commit to blogging more? No, but I'll try. At a minimum something new will come along in a few years and I may be tempted to switch to that. 😉

As a power user, I feel this frustration too. I really do want to know what is being updated. There may be a particular annoying bug that I'm waiting to get fixed. Maybe it's a new feature that I might not know about otherwise. But as a developer, I have a second set of concerns that sometimes conflicts with what users want. So here's why developers don't (always) explain every last bug fix in release notes:

Time

Often, release notes are an afterthought, something that's done quickly as an app approaches release. Developers, or someone on the team, is given the assignment to write release notes. The team wants to see what updates in the store just as much as you do, and equally as soon. Release notes are an (important) task that gets ignored until it has to be done. And when time is short, shortcuts get taken.

Embarrassment

No software is perfect. No app is bug free. Developers are not coding ninjas (regardless of what recruiters think). The developer may feel that certain bugs reflect poorly on their skills. Writing quality software is difficult, and everyone makes mistakes. Sometimes those mistakes are extremely dumb and best swept under the rug, right?

Security

Some fixes are security related. It's not always wise to announce all the security problems your app had. Users may not update, and installing old versions of apps is not hard. If you announce your security problems, you potentially make it easier to exploit the app.

I'm not saying this is the correct way to handle security issues. I'm saying this way of thinking easily enters your mind. No one wants their app to be "hacked" or exploited.

Limited space

Did you know that Google only allows for 500 characters in the release notes field? That's stupid short. And it's also not enough to list all the bug fixes that occur in a single app release. More important features will get the majority of the space in the release notes and bug fixes get lumped together, if mentioned at all.

Apple is more generous and gives 4000 characters. That's almost enough space to write four JavaScript demos.

Laziness

Stop me if you've heard this before: developers are lazy. We work hard at being lazy. It's an overused trope, but has some truth. The last thing a developer wants to do is write release notes. Most of us like writing software. When preparing a set of release notes, it can be very time consuming to review every last issue that was fixed. It's just easier to say "yo, we fixed some bugs" and actually go and fix some more bugs.

The middle ground

I'm not saying I agree with all the reasons above. I think there is a middle ground. Something between the spartan "bug fixes and performance enhancements" and a full copy of the commit log.

My personal strategy is to put the following in the release notes.

• New features
• Major enhancements and changes
• Significant bug fixes, especially if users have been reporting the issue

Users, I understand your frustration. I want to see good release notes. Hopefully it gets better. Especially frustrating are especially terse notes:

Bug fixes

(Google, I'm looking at you again ಠ_ಠ)

In the end, my illustrious career working for The Mouse didn't last long. I quit after four days (that's a story for another time). But during that time I learned two valuable lessons:

1. Some days your boss is The Mouse, some days your boss is "The Rat". (I had The Rat unfortunately).
2. The customer may not always be right, but they're still our customer.

Software customers

Working in software development, there is always a customer. Sometimes it is an actual paying customer, other times it's another department within the company. Both types of customers, while different in many aspects, share one commonality: they don't do software development full time. At best, the customer has utilized your services in the past, and understands the process. At worst, they've never interacted with software development before and have movie-link expectations.

I've often found that the customer thinks they know what the want. As a consultant, customers would come to my company and ask us to create a solution to help them solve a problem. They have nebulous needs such as "we need a website to accept applications" and "we need an app to reconcile our accounts payable and receivable". The solutions to these problems can vary greatly, depending on what is truly needed.

The true need

And that's the hard part. Finding out the true need from the customer. The customer has spent some time thinking about what they need, and has an idea of how that might come to fruition. "Build a website, something something yada yada, applications processed". As software developers (and business analysts, QA engineers, project managers, and so on), we've been on this ride before. We know what's coming. It's the eternal battle of expectations versus a true understanding of what's needed. It's usually a trying journey. The customer is likely wrong, and it's our job to make things right.

Saying no

So, in the name of quality software, we tell our customers "no". We explain to them why they're wrong, or slightly off-path. We put them on a better path. Sometimes we do it without even telling them. "They'll thank us later", we tell ourselves. We've taken some moral high ground that allows us to do the opposite of what the customer wants — I mean — thinks they want.

Two endings

This usually ends one of two ways (and depends on how you treat the customer). In the happy ending, we've helped the customer to see why their original plan wasn't quite right, assisted them in coming up with a better solution. One that both parties have worked together to achieve. The customer has been a part of the process. They have learned. They're thankful. They'll enlist the magic of software development again, and have an even better experience the next time.

Or they won't get what they want. They'll be told they're wrong constantly along the way. They'll go along with (almost) anything you say, believing that you, as the expert, know how to sail the confusing ship that is software development. In the end, they'll have a solution that, according to the new direction you've set the project on, works as agreed. And they'll be confused, bitter, but contractually satisfied.

Becoming "The Rat"

So how did you become "The Rat"? How did the journey to this perfect solution end horribly? Why didn't you see this before?

I don't know if there are any easy answers to how to fix this problem. You've taken the relationship between you and your client for granted. They gave you trust, as the expert, and you used that trust to steer them away from what they needed. Or perhaps to you did deliver what they needed, but through some of the most treacherous waters they'll ever travel.

The best advice is to take preventative action. To see the situation before it happens, and to fix you (and not the customer). This is hard advice to follow until you've made the mistake. But there are warning signs. If you are resenting you customer at any point, especially the beginning, you've probably set yourself up to be The Rat.

Communicate regularly. Let the customer know what you're thinking, why you're thinking it, and what you've seen happen in similar situations. Help them to discover the answer. Getting the answers for free deprives the customer an opportunity to learn and grow. As tempting "just trust me, we need to do it this way" is, that confines the result to some mystery the customer can't explain.

You won't be able to be The Mouse every day, with every client. But put yourself in their shoes. Try to understand how they feel and what the gaps in their understanding are. Build the bridge with them, not for them.

If it doesn't happen, it's not an error, right?

When determining how to test an application, you often test based on what you expect the application to do. It's a very reasonable approach, right? Given some input A, expect result B. You're happy and move on. But what about C? It doesn't always occur — should it have occurred when B occurred? How can you be sure? In fact, there are probably conditions when C should not occur. This just got complicated.

How do you find something that's not there?

Sometimes the volume of data is overwhelming. Imagine verifying that a 40 page document isn't missing a word. That's not trivial. A previous project of mine was to ensure a six volume set of laws got printed correctly. Not only did it have to look right and contain all the new content, but we had to make sure none of the old content didn't get changed by accident.

Never mind the small fact that the law of the land needed to be represented accurately, replacing a volume within that set was very costly. It can be costly to your organization to make errors. (As an aside, corrections where done as single page replacements when possible. Stick the new over the old, and go about your business.)

Controlled testing

The system we replaced on that project consisted of a mainframe application and lots of human input and proofreading. The proofreaders checked not only the content that changed (added, edited, or deleted), but the surrounded content as well. Although an inefficient use of human resources, it does provide a simple solution: testing against a known state.

The only way to keep your sanity when doing these large checks was to check against a known, or controlled, source. You can simulate this in your acceptance testing or even your unit or integration testing. Be sure that the source data you are verifying against is accurate, and the authoritative source.

Only test affected functionality and data

Six volumes takes a long time to read, let alone proofread. How does one ensure that content doesn't go missing or changed by accident? Each book was broken into chapters. On average, 10% of the chapters changed each year. It was mostly safe to proof only the chapters that changed (and even then, sections within those chapters). There was a chance that a chapter or section could be omitted, but safeguards where in place to ensure they were still there. The moral of this example is to work smarter, not harder. Only test what you have to. You can test more, but never less.

Knowing, half the battle

The key is to know when to look for errors of omission. The first step (for everything, it seems) is to admit you have a problem. Once you know to look for errors of omission, you can test for them as well. Be sure to limit what you test intelligently, and test against the authoritative source. In time, you'll get better at spotting the circumstances in which an omission can occur.

I arrived at my new assignment and promptly setup my development environment on my workstation. I was placed on a small sub-team with three others, led by a newer hire that knew Java very well. Even though I was nervous, I felt good about my situation. I had been in a similar situation on my first project while I was learning ASP. Even better, I now had a few years of professional experience. The non-programming parts of software development wouldn't be as foreign to me as it had been just out of college.
As expected, much of Java looked foreign. The language itself was familiar, but the projects and applications were structured nothing like I was used to. On top of that, we were using a bunch of weird middleware products I'd never heard of (and would never come across again after this project). I was having a hard time getting a handle on everything. There was so much to learn, and that was just my small little sub-team.

I plodded along in my assignments, turning out what I thought was decent code given the circumstances. I knew what I wrote six months down the road would be a lot better, but that was the best I could do at the time. I interacted with a few of the other sub-teams, ensuring our work integrated with theirs. All the sub-teams were growing, and quite a few new developers joined us on the project. All of them had more Java experience than I did. I was now the odd man out. The Microsoft guy on the Java team.

A quick aside — I enjoy helping people, especially helping others learn to code (or learn to code better). I am very grateful for the mentors and coworkers I've had over the years that have taken time to help me be a better me. The least I can do is give back.

Given my nature, I found myself working with another developer on a different sub-team. I don't recall how we got on the subject, but he was struggling to create the code for the UI in the design documents (a UI that only corporate apps can dream up). This developer had been working on Java his whole career, and our careers were similar in length (2-4 years).

As I helped him, I had a one of the more important revelations of my career: It didn't matter what the language was, the core concepts and patterns used where universal. While the language might change, the same things I'd done in ASP where just as applicable in Java.

I found myself in this situation a handful of times. For the first time on the team, I felt like I was adding significant value. And I wasn't even working on my assignments half the time. The project lead was a friend, and I found myself talking to him in his office (usually after hours when he wasn't in his endless meetings). I kept him briefed on what I was doing and how I was assisting the team.

A few weeks later, the lead called me into his office. "Jason, I have a new assignment for you."

Great, I thought. I finally found my groove and now things would be changing. I prepared myself for something new, but not quite what he had in store.
"I want you to be a utility developer."

What's a utility developer, I thought. That sounds weird. I wasn't sure I wanted to be a utility developer, whatever it was.

"We're going to take you off your [sub-]team and have you assist everyone on the project, as needed. You won't have any tasks on the project plan. Just help anyone who needs it and keep the project moving forward."

My mind was blown. On the positive side, this was high praise. I was helping people and that provided more value than working on tasks directly. On the other hand, I was going to have to learn, at least at a high level, all the various technologies and parts of the whole system. I cautiously accepted my new assignment and got to work.

Over the next few weeks, I helped all the teams, as needed. I learned more technology in those weeks than I had on the project to date. I got to talk to everyone, learn from everyone, and generally grow myself more than I had in a long while. I continued to learn that I could tackle any problem (except for being on time for the 8:30 AM daily meeting).

Unfortunately, the role of utility developer didn't last forever. I don't recall exactly how it ended. I did leave the project before it was completed (only to return later, it was large and long project). Perhaps I was needed in classic ASP land again. Whatever the reason, I left the project with more confidence than I had had at any point in my career up to then.

Soon after, I started to be the team/project lead on many of my projects. I'm thanking for the time I spent as the utility developer, doing a little bit of everything, but most importantly, making sure the project moved forward.

I've written about presentations before, but failed to go into any detail about configuring your IDE of choice. Mine for tomorrow will be Visual Studio. Since it's been a while since I've presented, I didn't quite remember the required settings to change the fonts. And Visual Studio has a lot of settings:

Thankfully, I found the article I mentioned above, and saved myself a small fortune of time trying to find and toggle all the correct settings. I've perfected the following quick process for my presentations.

4 simple steps to a better presentation

Step 1: Download this Visual Studio settings files

Step 2: Import into Visual Studio via the Tools->Import and Export Settings menu item

• Select "Import selected environment settings" and click "Next"
• Select "Yes, save my current settings". Do this so you can revert back after your presentation. Type in a name, I called mine "dev.vssettings", and pick a folder to store them in. Click "Next"
• Click "Browse..." and find presentationmode.vssettings. Click "Next"
• Leave all the defaults, and click "Finish"

Step 3: Give your presentation with fonts the back row can read

Wow, such big

Step 4: Revert back to your original settings by repeating Step 2 and choosing your saved settings (you did save them, right?!)

The supposedly fair system of user reviews is horribly broken. The process was ripe for gaming. And gamed it has been. Companies optimize their apps and websites to get you to leave ★★★★★ reviews. EA, with their Dungeon Keeper on mobile platforms has optimized this to the extreme:

Clicking "5 Stars" takes you to the store to give that ★★★★★ rating. While clicking "1-4 Stars"...

Emails, as far as I know, don't show up as app store reviews. Instead, you get ushered away from app store to some back room where no one knows what was said. That, in theory, leads to more ★★★★★ reviews and a higher score. EA's tactic may have gone unnoticed if it wasn't for other issues with the game.

"Beating" the system

Less than satisfied users on the other hand, in response to all the ★★★★★ reviews, or perhaps just in anger and spite, leave ★ reviews and scathing comments. "I'd give it no stars if that was possible!" raves one review. "Doesn't support feature X, thus ★." says another.

In response to EA, the masses gathered to "correct" the injustice: an unfair playing field. Their response, ★ reviews. This behavior is called Griefing.

The test

Go to Amazon, or Best Buy, or the App Store or Google Play and read a few reviews. Play close attention to the ★ reviews.

Results

What did you find? I went to the Apple App Store (which is hard to navigate from a browser, but I digress) and looked at the first app in the first category: iBooks.

Here are the three reviews I saw:

Pay special attention to the middle review. Other than a thirst for violence, what sticks out? To me, it's the desire to get a single thing changed (the new UI design to match iOS 7's massive overhaul). So does this ruin the experience? I don't know, I'm not the review's author, shr00mie. Only shr00mie knows how shr00mie feels. And if we take shr00mie at his or her word, the app is ruined. Reading books is ruined.

The review has an agenda. The agenda is to get something changed. And the way the user has decided is to attempt griefing with a ★ review. This behavior exists anywhere a user can leave a review. Let's check the Google Play store. Maybe it's just Apple zealots, right?

This comes from the first app the store shows, NCAA® March Madness (so glad they got that ® mark in there. I was totally going to steal their mark!)

This was the first review of the app. In a way, the reviewer is correct, if the user only installed the app to watch women's basketball, and it only shows men's basketball, then it's useless, and worthy of a ★ review. But the app's description states that it allows "unlimited access to live streaming video of all 67 games of the 2014 NCAA® Division I Men’s Basketball Tournament". I'll let you be the judge.

How I handle user reviews

Honestly, I've had my fair share of "does not support move to SD" reviews (on Android, the ability to run an app from an SD Card vs. internal memory). Does the app deserve a ★ review because you have too many apps installed on your phone?

I no longer trust review scores. Between the "I ran this app for 2 minutes and it looks awesome ★★★★★" and the obvious attempts at review griefing, the signal to noise ratio is much too low for me.

Like any project, my new project started accruing technical debt. I was faced with the decision that every project is: pay back the debt or build shippable (and thus profitable) features. Most projects choose the latter. That's probably the right decision in some cases. But being scared that one day the new project would be the old project, I couldn't live with the decisions made weeks earlier. They didn't sit right with me.

The other developer and I decided to fix them. It was now or never. Once we got out of the "build a thing that compiles and does the first thing" and into production, there wasn't going to be a lot of time to circle back around. We'd be any other project at that point. Always enhancing, always maintaining. As we found the nasty regions in the code, we tore them out and replaced them with something better.

Technical debt is said to accrue interest. The longer it sits around, the more code that gets piled on top of it that makes it harder to change and fix. That's one reason why we were able to pay so much back. The cost to do so was not yet high.

I'm not saying you can't go back and pay back your technical debt at some point in the future. I think you should. Business needs in general don't allow development teams the time they need to fix everything. We sometimes settle for what's the worst code, or what's easiest to fix. Slow and steady in those cases.

If you get a chance to pay back your debts, do so. The sooner you pay them back, the easier it'll be. And you'll feel a lot better about the code you leave behind.

Google Authenticator now handles this situation correctly, and this article is less useful than it once was.

Original Article

Microsoft recently added two factor authentication. You should add this to your account. It's a good thing.

I recently tried on my Android phone to scan the barcode, but it wasn't working. My co-workers and I figured out that the Google accounts we already had setup on the Android authenticator app shared the same email address. Both Google and Microsoft were using that for their account name, so the second account wasn't being added.

To get around this, I manually added the account and gave it a name other than my email address. I now have notmyrealemail@gmail.com" for Google and "Microsoft" for Microsoft.

Creating External Tool entries

The first step to setting up the integration is to create external tool entries for the various commands you'd like to launch from Visual Studio. Using the following steps, you'll have one or more hg commands at your disposal.

1. Go to "Tools -> External Tools" menu item.
2. Click "Add".
3. Name the tool in the "Title" textbox. I've chosen "hg annotate", "hg diff", and "hg log".
4. In the "Command" textbox, put the path to TortoiseHg, typically "C:\Program Files\TortoiseHg\thg.exe"
5. Fill out the proper arguments. The $(ItemPath) variable points to the current file. It's good practice to surround the item in quotes, as you may have spaces in your path. Here are the various agruments for the commands I use:
   1. Annotate: annotate -n $(CurLine) "$(ItemPath)"
   2. Diff: vdiff "$(ItemPath)"
   3. Log: log "$(ItemPath)"
6. Within "Initial Directory", put a path within your repository. I've chosen $(ItemDir) for simplicity. You can also use $(SolutionDir) or one of the others.
7. Check "Close on exit", or you'll end up with a pesky Command window left open.
8. Note the position of your entry in the list (8th, etc). You'll need to use it later.
9. Repeat steps 2 through 7 for the various commands, and click "OK" to save.

Adding context menu items

While you can use the entries in External Tools as is (Tools -> hg log), it's useful to have them in the various context menus in the system.
Some of the commands are dependent on the type of file open, so open a code file before you start.

1. Go to "Tools -> Customize" menu item.
2. Click the "Commands" tab.
3. Click the "Context menu" radio button.
4. Choose an appropriate menu item from the "Context menu" dropdown:
   1. "Editor Context Menus | Code Window" adds it to the right-click menu of the code window.
   2. "Other Context Menus | Easy MDI Document Window" adds it to the right-click of the document tab.
   3. "Project and Solution Context Menus | Item" adds it to the right-click menu of the files in the Solution Explorer.
5. Click the "Add Command..." button.
6. Select "Tools" from the "Categories" listbox.
7. Now the fun part. Select "External Command x", where x is the position in the External Tools entries. You remembered to remember that, didn't you?

Bonus

As an added bonus, this guide also works in SQL Server Management Studio.