Why Blog?

I was going through my old Twitter bookmarks and I have this from Jack Rhysider on blogging. Jack makes one of my favourite podcasts, Darknet Diaries which I recommend if you are interested in cyber security stories.

If you’re in IT, I highly encourage you to write a blog.

Here are 17 reasons why you should be blogging.

1. Don’t think of the blog as some new profound insight that makes you look smart. Instead, just write notes to yourself. If you make the blog useful to you, it’ll be useful to others.

2. Throughout your career you’ll stumble onto lots of great tips and advice and commands and tricks and ways to do thing. Blog all that. You will remember it better if you write it down. And it’ll be easy for you to find it later.

3. You are in IT, so how’s your web presence lookin? You know there are people who have a bigger web presence than you who live out on a farm and know nothing about computers? This is your passion. Show us what you can do!

4. Have you ever run into a problem, Googled for a solution but couldn’t find one? You’ve gotta keep doing trial and error until you fix it. That’s gold blog content. You’ll have the only page on the internet with how to fix that problem, and maybe save lives.

5. Do you keep seeing people ask the same question over and over that is so obvious to you? Blog that. Then point people to it every time you see the question. Psst, your co-workers will bug you less if you point them to your super helpful blog posts that answers their questions.

6. The more you explain technical concepts to people. The better you’ll get at understanding technical concepts yourself. Sounds backwards but it’s true. Teach to learn.

7. The most underrated skill to have in IT is ability to communicate effectively. Blogging is leveling that skill up. Are people getting what they need efficiently and effectively when they land on your site? Can you explain the concepts even better? Rewrite it, level up.

8. If you’re sending people to your blog and it’s not helping them, learn why so you can do better. My system is to clearly state the problem first, then write the answer after. Then explain details and alternative solutions. Don’t waste time with making people scroll for the answer.

9. If you find yourself having to Google answers to the same problem over and over, that’s good blog content. Write down exactly how to solve that problem that’s most effective for you, and it’ll be faster to reference your own notes, and it’ll be better suited to you.

10. Chances are, if you work in IT, the only people who know you’re any good are your co-workers and customers. Blogging expands that and suddenly there are people all over the world who respect you and appreciate your skills. This can open a lot of doors for new possibilities.

11. Taking classes on a technology new to you? You’re taking notes ya? Blog those notes! Trust me. Taking your notes from class and rewriting them into your blog will help you understand the content so much better, while helping others too. It’s a magical thing.

12. Now once you start putting content out into the world. Some magic stuff happens. First people will start correcting you. It’s inevitable. Don’t take this negatively. Take it as an opportunity to learn how to do something even better or more thoroughly.

13. Strangers might write to you thanking you for helping them. And let me tell you, fan mail is one of the best drugs. Because it’s pure and clean and feels great.

14. Did you know blogging was the precursor for my podcast? I blogged for 7 years before starting a podcast. It taught me how to write better, and produce content. It was from there that I got the idea and skills needed to podcast. Now I podcast full time. Blogs take you places.

15. If you blog for a while, you’re now a content creator with an audience. Chances are the blog won’t be the last thing you create. You can use your blog audience to seed your next project. My blog has been one of the best places to get new listeners for my podcast.

16. Bloggers can make money. You can put ads in your blog, get Brave rewards, or even just get tipped by random strangers.

17. Oh yeah and when you blog you have to solve all kinds of problems like domain registration, DNS servers, hosting, backups, web design, securing the site, and HTML/CSS/JS. The more you have your hands dirty in doing different IT stuff the more well rounded you’ll be.

So to recap. By blogging you will become a better writer and communicator, learn the concepts better, open new opportunities, have a fantastic notebook for self reference, maybe make money, become appreciated by more people, and show off your IT skills.

Test Specifications

Many  years ago, when I was a Software Tester, I remember when we had to write a Test Specification based on the work that the Developers had planned. This was for both Enhancements and Bug Fixes (so new features and changes to old ones).

It would be a Word document, with the Item Number, Title, and then a description of what you would test (the description would be a bit more high level than the step-by-step description featured in an actual Test Case).

You would spend weeks writing it, then you had to get it approved by all the developers, or the Dev Lead. The developer often then told you it’s nothing like you imagined so you had to rewrite it. 

Sometimes they would demo the feature to you so you had a better idea. If they had no comments, I often felt that they didn’t read it.

When there was a new Developer who wasn’t familiar with the process, he “rejected” a Test Specification because of some grammatical issues. I think it was something to do with the wrong tense, and not using semicolons. The Tester was fuming, but he was quite a belligerent character.

I think we often worked from the Bug description, or some comments from the Developer. However, quite often, the comment section would be the Developer writing something generic like “test bug is fixed”, “check data is saved“. If it was more detailed, sometimes you would paste the developer’s notes and change a few words – and have no idea what it meant until you saw the finished thing.

The Verdict

I think both Developers and Testers saw Test Specifications as a waste of time. The Developers weren’t enthused to read it, especially when most people rewrote what the Developer provided, and that might not be the full test coverage needed. The Testers should be adding more value by using their existing knowledge of the system to come up with additional scenarios to cover “regression testing”. 

I think the only advantage is to quickly verify that the Developers and Testers were on the “same page”, but that only works if the Tester has not used the developers words and tried to illustrate that they do understand the upcoming features.

I think it eventually got binned off for what we called “Cycle Zero Testing” which was where the developer quickly demoed their changes; which I think was still hated by the Developers but was easier to understand the value, and was a more collaborative between the two roles.

Commit Messages

As a developer, you need to “commit” your work into source control. When you do this, you need to provide a message that describes the change. A bug fix or enhancement can consist of a few commits. When you use a source control like Git, you can even “rewrite” the “history” by using squash/rebase commands.

When I am writing code for my job, I often put a bit of thought into the wording to make it clear and professional. If it is for a personal side-project, I sometimes write meaningful messages, but sometimes I may group together multiple fixes, then come up with something generic like “Bug fixes”, or might commit more experimental work-in-progress under a name like “attempt” or “x feature part 1”.

It’s quite frustrating though to see colleagues write generic messages like “bug fix” which doesn’t describe what it is fixing, or how it is fixing it. Seeing messages littered with spelling mistakes is also annoying and unprofessional.

Examples include:

  • “EventNotificationBugFix After Resolving James’ Comment”
  • “bug resolved”
  • “Dev test changes from tester” (literally what does that mean?)
  • Updated the findCorrectCodeSp to findCurrectCode.
  • Taken off completly the fix Amanda done for the fix for 25477 and fixed. Included the fix for 8017 as well
  • Fix for SQLCrop issues (should be SQL Cop, our Code Analysis)
  • Fioxed further typos (ironically creating more typos when fixing typos)
  • fixed the failed unit testes (testes rather than tests. Brilliant)
  • “Post Christ’ comments re coding standards” (it’s the second coming of Christ to teach us coding standards! They meant to write Chris.)

There was a guy who worked in our short-lived Scotland office who sounded like an absolute nutcase and I have never seen someone not take their job seriously like this:

  • instructions unclear, got dick stuck in tfs 
  • what a waste of eyes
  • but fuck wasps
  • be nice to bees
  • what if there were landmines in dinosaur times

A colleague recently showed me this website https://whatthecommit.com/. I don’t know if they are based on real messages, but it shows you a new message every time you refresh. Most are pretty basic along the lines of “does this work”, but there’s some more outlandish ones if you persevere and refresh many times.

One of my team members recently submitted a change that was labelled “Crash when cancelling out of the dialog”. That describes the bug that he fixed, rather than what he fixed. Another team member provided the following good advice:

The change looks good, but your commit message isn’t describing the change. Could you just reword it so that it completes the sentence “When applied, this commit will…” please. Another way of looking at it is that every commit should read like an instruction in a to-do list. I’d use something like “Return empty collection if user cancels out of the dialog”.

Senior Developer

A stricter idea of commit messages is described here: https://www.conventionalcommits.org/en/v1.0.0/

One of our Principal Developers loves linking people to this guide https://cbea.ms/git-commit/. One interesting idea is to “Use the imperative mood in the subject line”, whereas most people would write in the past tense.

Having a clear history of file changes helps you when it comes to finding which change caused an issue, and also gives you a better understanding why it changed.

Virgin Media Hub 3.0

For my home internet and mobile sim, I have Virgin Media and a Virgin Mobile sim. They contacted me saying they were switching me over to o2, so in future, I would be billed by o2 instead, but I also qualify for a few extra benefits for the same price.

Once that was activated, they then said – because I have Virgin Media and an o2 mobile Sim, I now qualify for a bonus speed to my Virgin Media home broadband. Not sure how that makes any sense and why I didn’t qualify before, but cool – free stuff.

However, my current router cannot handle the new speeds or something, so now I have to have their latest “Hub 3.0”.

When I received the package, I had a quick look through the instructions and it seemed as simple as plugging it in. The only thing of note was that when you think you are ready to connect your devices, you need to look at the lights on the Hub:

“When the Wi-fi light is on and the base light is solid white, you are ready to move on. The arrows may still be flashing green”

Instructions

I assumed the flashing arrows meant it was updating (but couldn’t see anything in the instruction manual), and when they stopped flashing after 1 hour (why does it take 1 hour to update!?), I had a stable green Wi-Fi light, stable green update arrows, and a stable yellow main light. So what does that mean? it doesn’t match their description.

After a minute, the green update arrows and green wi-fi light went out, and I was left with a stable yellow main light and no internet connection. So I turned it off and on again. Same sequence of events happened.

So I reconnected my old router to check the internet was still working. It was.

The next day, I asked one of my colleagues (who I knew had Virgin Media broadband). He said he had a Hub 3.0 and his just has a stable yellow main light and had no idea what I was on about when I told him about the white light that the booklet mentioned. It was years ago when he had set his up, but he thought it was as simple as plugging it in, and away you go.

So after I logged off work, I plugged the “Hub 3.0” in again and got the same sequence of events. This time I went to the router’s IP page http://192.168.0.1/. Is it updating? Why so many updates?

Update in progress 
Please wait before updating any settings. 
Refresh

I waited over an hour, but I was still stuck on the update screen. I turned it off-and-on again. Still says it is updating. But there’s no green arrows on the router itself. Can we trust the arrows?

I check Twitter and find a few people from various years with the same problem but some say that Virgin call centre staff resolved it – but didn’t say what the resolution was. Then there were some unresolved cases of people Tweeting into the void.

So since it was late, and I assumed Virgin’s call centre wouldn’t be available, I waited till the morning. I then plug it all back in, and call the number in the booklet:

“Connection issues? if you’re still having trouble connecting after following all the steps, waiting 30 minutes for your Hub to set up and making sure the connections are secure – call us on 0800 953 9500”

Instructions

I was greeted with an automated line asking me for my account number. I hung up and went looking for the letter. I call back, type in the account number, then it asks me if I would like to link my phone number to my account for faster calling in future. 

That sounds great because I hate having to read out an account number, and go through the “security” checks. If I can bypass one or both of those, then it would be amazing. They always ask you for part of your memorable word and it always trips me up because I have only needed to call them 3 times in 9 years or something – so it is easy to forget. I was convinced I knew it, and this would test out my thoughts, so I went through the process of trying to link it. 

The automated voice instructed “press the key that corresponds to the first letter”, so the 2 key would represent A, B, or C. Maybe not so secure when there’s ambiguous answers. I typed the 3 numbers in, and apparently it was wrong. So I hung up.

I went to the website, account details, “change memorable word”. You have to choose a word between 8 and 10 characters long, but it’s not quite a word because it needs 1 number. With that level of specific criteria, it probably makes it less memorable too. So I type in 9 characters and a number to get 10 characters in length. Apparently it didn’t match the rule “8-10 characters long”!? So “8-10” actually means 8 or 9?

Eventually I managed to set it to something slightly memorable, so call back. Enter the “Account number”, “memorable word”. Right, as long as I call using this mobile number, it should get me straight through in future.

Right, can I speak to a human now? no. 

The automated voice says they know I have been sent a new Hub and if I press “1”, they can send a signal to activate it.

WHAAAAAAAAAAAAAAAAAAAAAAAAT!?

Me, raging

The instructions never said that. It said to wait 30 mins for a solid white light and wi-fi light, then only call if there’s connection issues. Yet this number is an automated line that is VITAL to call.

So I press “1”. The voice says it “may take 1 hour for the connection to activate”.

What!?

Super fast broadband, like 264 mbps and you are saying it takes 1 hour to transfer 1 signal to tell the router it is valid? What the hell. I was supposed to be working and thought I would be offline for 15 mins.

After waiting 1 hour, there’s still no connection. I waited another 15 mins. I checked the router settings page; “Update in progress”. It’s either lying, or completely broken.

So I called the number again to see what would happen. The automated voice tells me my account number is linked to my phone, so I press “1” to accept. Now I have to enter 3 letters from my memorable word. At least not entering the account number is convenient. I put my letters containing the account number in the drawer; I won’t be needing those again.

The automated voice tells me that the “signal” had failed to activate my router, so I have to be passed onto a human. I connect straight away, and first I need to state my name. Now I need my account number. WHAT!? I can’t have gotten this far without my account number which I had linked to my phone. So I scramble to get the papers out of my drawer so I can read off the account number. Now I need to specify 3 characters from my memorable word. (╯‵□′)╯︵┻━┻

If it is a challenge to make a calm guy like me turn aggressive, then this is certainly the way to go about it.

So I explain that I have this new Hub and it doesn’t work. She asks me what lights I see, and she says it should be working. I then get put on hold for a minute, then she says

“We haven’t registered this Hub at our end”.

Virgin call centre staff member

Brilliant. Why is that even a thing? The connection is coming through to the inside of my house (my old router works perfectly fine). Why do they need to authorise a device inside my house? They sent it to me too, so why wasn’t it automatically registered? You would think they would have the process perfected after all these years.

So after holding a bit longer, she said she would then send the signal but it may take an hour. She then asks if “I am happy with the resolution?”.

“Eeeer. Dunno. If it works, then yes. If it doesn’t then no.”

Me, uncertain

“It will work, sir. We will send you a text message when it is activated.”

Virgin call centre staff member

The connection actually came on after 1 minute.

1 hour 45 later: Virgin via text: “We’ve activated the new Virgin Media kit

Here’s a list of things that are dumb:

  1. If you send someone some new hardware, make sure it is registered on your system
  2. If it requires the customer to make a phone call, make sure it is clear in the instructions
  3. The phone number should also state when the line is open, and if it is automated or not.
  4. If there’s lights on the hardware device with different meanings – put them in the instruction booklet
  5. Don’t tell the user they are looking for a white light, when it is actually yellow.
  6. Don’t make a page stating “Update in progress” when the status is “Unregistered device”
  7. If there is an Update process, explain to the user what this means and how often it should occur, and how long it should take. What if I turn off the device whilst it is updating? Does it become “bricked”?
  8. Don’t send a text 1 hour 45 minutes late.
  9. Don’t tell the user they can register the account number to their phone, then ask them to read out the account number.
  10. Don’t say you can create a memorable word of 10 characters, then tell them they cannot.
  11. As a human, don’t ask for 3 letters of a memorable word, and when the customer gets it wrong, ask for 3 different letters. There’s a good chance you could piece what the full word is by putting together the answers. I assume the call-centre staff cannot see the full word, but it wouldn’t surprise me at all if they could.
  12. There must be a better way of activating a router than via signal that takes up to 1 hour. I assume there’s some serious leeway here, but it’s not good to keep a customer waiting that long before calling support again.

Software Development Process

When a new development team is created, managers insist on creating a “Ways of Working” which essentially comes down to describing the software development and testing process in the ideal way.

Then after a few weeks, you end up just resorting to the default way of working.

The “ideal” way assumes that the Testers can provide ideas and inspiration to the Developer, and when the Developer writes the fix, the solution won’t deviate from their original perception. Therefore, all the Test Cases are written up front, and none are needed to be written after.

Here is an example that one of my former teams came up with:

Before fixing the defect

Analyse together 

  • Make sure you pair up as a developer and tester to work on the defect.
  • Review the problem together
  • Understand how to replicate the fault
  • Understand the extent of the problem (all regions, all set-ups, all environments?)
  • Do the initial debugging to understand where the problem lies

Fixing the defect

The developer MUST 

  • Make sure there are unit tests to support the current functionality
  • If there aren’t unit tests then implement a simple refactor which will allow appropriate unit tests to be added
  • Add unit tests that prove the defect (which will fail)
  • Fix the defect
  • Get it code reviewed
  • If you are working on code you are not familiar with, get 2 reviews, one of which must be from an expert
  • Run all the unit tests and prove the fix

The tester MUST 

        â€˘ Write test cases with steps and expected results for the initial test cases. They must

                â—‹ Be clear and unambiguous

                â—‹ Cover the different scenarios/circumstances/options

                â—‹ Not test things that are irrelevant

        â€˘ Once written, set the state to “Review” and assign to the reviewer

        â€˘ The reviewer

                â—‹ Adds comments as appropriate

                ○ Set the state to “Ready” if Ok, or back to “Design” if it needs changes

                â—‹ Assign it back the test author

        • Only use Given, When, Then if you are using Specflow to automate your tests

        • Only use exploratory testing

                â—‹ If you have passed a Rapid Testing course

                â—‹ And you have a clear understanding of testing heuristics

                â—‹ And you plan and classify sessions, keep session logs, run debriefs

                â—‹ And all the specific test cases and all regression test cases have been executed

        â€˘ Create regression tests of the functionality

        â€˘ Create test case(s) to prove the defect

        â€˘ Get the tests reviewed

        â€˘ If you are working on functionality you are not familiar with, get 2 reviews, one must be from an expert

Assure the Quality

  • Review the actual changes together
  • Understand the logic
  • Understand the scope
    • Minor/contained (inside a method that’s inside a class that doesn’t affect anything that’s outside it)
    • Medium/impacting (a change that impacts outside it’s own class or is called from elsewhere in the system
    • Major/widespread (a complete refactoring of existing code or large changes to core features)
    • If they don’t understand the logic or can’t establish the scope, escalate to the Technical Manager
  • Execute the tests
  • Attach and link all work items and evidence together

Duplicate Wikis

Our repository has a ReadMe with some instructions in it. We also have 2 sub folders each with a similar ReadMe. We also had a team documentation website where similar instructions were pasted in.

I raised this with my team that if you want to change an instruction, you have to paste it in multiple places and it’s a bit silly. I did try and simplify it somewhat by reducing the amount of information: Just by using hyperlinks to direct you to where the more detailed information was.

I took some annual leave, and when I came back to the office, I found that we now have a GitHub Wiki and the ReadMes are closer to what they were before (my hyperlinks removed), but now with even more information on them.

Additionally, there was a Pull Request from a team member to update the main ReadMe with some incorrect information. I point it out to them, and they say “I pasted it in from the other ReadMe”.

Well, this is exactly why we don’t duplicate information, and why I raised this as an issue to the team.

If this was code, and not text, I know they wouldn’t do it. If you write some lines of code inside a method and need it elsewhere, they wouldn’t copy and paste it like a Junior may do. You would just reuse the method by calling it directly. If you copy and paste, then change one file; then there is a difference in behaviour and a Bug is introduced.

Since we are talking about text, you shouldn’t copy and paste it, you should use a hyperlink. Then you can just change the main source. Then there are no conflicting instructions. 

Always have one source of truth.

This is what I did. Why was it undone?