Jonathan's Blog
name

Jonathan's Blog

Mindful Leadership and Technology


TagSoftware Development
Featured

Rebuild Application Rebuild Software Development

The Many Guises of Hazy Rebuild Requirements

Posted on .

Clients frequently request that we use existing applications as the basis for work when we are rebuilding or recreating a system with them.

This is very difficult. It can work, but it is much less effective for developers and results in a lot of iterations as the dev team goes back and forth figuring out what an application needs to do. It leads to a lot of bugs that are only discovered in UAT.

In the beginning it is much more efficient for your business stakeholders, which is why they ask for it. Why go through the existing application and document it? That's a lot of work for users and business people, not to mention the BAs you have to pay to do it.

In the end, the same people who didn't want to go through the process of documenting will be mad because it is taking so long. It is your responsibility as a developer, lead, or PM to set the right expectations in the beginning.

If your stakeholder (whether client, boss, CEO, etc.) requires you to work this way you need to expose the risk and set appropriate expectations. The very best case scenario is that you have to set aside time for late project iterations when you run into these challenges. The worst case scenario is that the project will drag on so long that will be cancelled. It happens all the time. Also possible: you fixed-bid the project and put your company out of business trying to complete it.

Setting the right expectations can be difficult, and that is a topic for another post some time. My goal today is just to describe a few of the ways this has come up over the years, so you know what to look out for.

  1. Just make the new app do what the old one does. Why do you need requirements? An all-time classic. Why not? I mean there's already code, how hard can be to just: read it, understand it, understand all the subcomponents and UI, assess whether or not it is still necessary, talk to users, and figure out how to test it. It definitely wouldn't be easier to have that done and approved before you start development. Danger level: Red Flag
  2. Preserve the business logic, everything else you can get rid of. This assumes that preserving the business logic is easy, which it usually isn't. Even when someone has done a good job of separating business logic from UI and data access (very rare) often the technical and business requirements of the rebuild make reusing the code in its original form impossible. Danger level: Yellow Flag
  3. We'll figure it out as we go along. This one can seem reassuring in that your stakeholder has seemingly granted you permission to iterate. But be careful here: set expectations, ask follow-up questions, establish what 'figuring it out' will really look like. Danger level: Yellow Flag
  4. There's a lot you can re-use. Just tell me what it will cost to rewrite the things that you can't re-use when it comes up. You should assume that you are rewriting everything. If you get to re-use something that's a win. It will most likely save you a little time in testing, but not anywhere else. Danger level: Yellow Flag
  5. You don't need to talk to users. Bob knows everything about this application and Bob is your main point of contact. Unless Bob is the only user (and even then) he almost certainly doesn't know everything. Even if Bob isn't an ego-maniac (and he might be) you are still facing delays in understanding the system because Bob has to go ask someone instead of you asking them. Danger level: Red Flag
  6. This spreadsheet will tell you everything that you need to know about the system. AKA Our old system was a spreadsheet, just look at that. Usually these are worse than looking at code because in addition to code (like VBA) you also get things like embedded charts, formulas in cells, and obsure data access thrown into the mix, requiring even more detailed reading to understand. Danger level: Red Flag
  7. Jennifer developed most of the original system and she'll be working closely with you on this project. Usually Jennifer is retiring, and that is a hard deadline. Also, what does most mean? Danger level: Red Flag
  8. We have all the requirements from 20 years of work we did on the old system. You can read through that. To paraphrase Sartre, Hell is other people's requirements documents There are a few reasons why this is true, but probably the most profound is that writing the requirements document immerses the team members in the system. Without having written it, asked the questions, and fully digested the material then you or your BA will always be at a deep disadvantage. I wish this weren't true, but it is. At least 50% of the reason for documenting stuff is to make sure the person responsible really understands it. Danger level: Red Flag
Featured

Leadership Software Development Work

Three Types of Fun, Applied to Work

Posted on .

This came up in a meeting I attended. I described something a development team was working on as fun, and I was informed that it (creating peer-to-peer connections between Android devices) was Type 2 Fun, at best.

https://www.rei.com/blog/climb/fun-scale

I had never seen this before.

A lot of our work (hopefully) falls squarely into the Type 2 Fun category. Not that fun at the time, but fun to remember later, usually because I learned a lot and became better because of the work.

This is worth aspiring for in a career. If you find yourself having a lot of Type 1 Fun (regular, fun-while-it-is-happening fun) you probably either work at a skating rink and really enjoy the YMCA, are a little delusional, or a very self-actualized person.

Should you have some Type 1 Fun on a regular basis? Yes, you should. Can some of it be at work? Absolutely.

But a better achievement for our society is if a lot of us can sit around and say, "You know I learned a lot from that and it helped me excel in my career." If we can say that a lot of the time about a lot of the work we did, we've come a long way from where we were even 100 years ago.

Type 1 Fun is helpful and helps make people more productive. Type 2 Fun is necessary for the success of our companies and careers. And I do mean necessary - things that are a slog (Type 3 Fun) are unsustainable, in the long run.

I've certainly come acrosss some Type 3 Fun, also called, "Let's never do that again." But then, they are still jobs, even when it is your career.

Here's a quick reference, updated for the workplace:

Type 1 Fun: Remember that project where you learned a lot, everything was on time and on budget, and no one got frustrated ever? Me either. Remember that time you won the Fantasy Football League or had a great time at the Christmas party? Type 1 Fun all the way, and work related.

Type 2 Fun: Remember the difficult project where you started behind the 8 ball, worked long hours, but pushed yourself and came out the other side with a ton of knowledge? And you shipped a great product? Remember that time when you got fired and worked hard in your time between jobs so that once you landed a new job you were a changed person with different goals and a new outlook on life? That's Type 2 Fun.

Type 3 Fun: Remember having to do arbitrary work that didn't matter because it fit into someone else's system? Remember the client who used personal attacks on people because they were very unprofessional? That's Type 3 Fun, and it isn't migrating to Type 2 any time soon.

Featured

Bots Conversational UI Software Development

Bots Rising Continued - Creating a Bot with Dialogflow for Google Assistant and Google Home

Posted on .

I wrote some blog posts way back in the good old days of 2016 about a bot we developed for an intenral work tool. It ran inside of Slack. When we did the development we were basically writing code to handle all the states of the conversation. It was clunky and had some real limitiations.

Fast forward to more recent times - we bought a Google Home at the end of last year. Because I usually want to make something and not just consume information, I started to play around with Google Assistant and how to create an Assistant App for Google Home with tools on Google Cloud.

So right away I found myself working in the Dialogflow ecosystem. This was a big improvement over how we built our Slackbot in 2016 where we were hand-coding our state and writing a million if/else statements to handle the user interaction.

The Dialogflow designer interface is intuitive for creating your conversation. My biggest sticking points were working through the integration between it (Dialogflow) and my existing webservices. The answers were there in the documentation but it took some time to work through my SSL issues (doesn't allow self-signed certificates) and formatting of request. This was a little frustrating at times, but nothing out of the ordinary for using a tool that you haven't worked with before.

I also came across Let's Encrypt for solving my SSL issues. Let's encrypt allows you to get a real-ish certificate for development and test purposes. It is fast and automates several parts of the SSL cert process I've never seen automated before - very handy!

My Google Assistant App is submitted now and waiting for approval. I believe I adhere to all their guidelines, so hopefully they will approve me! Fingers crossed!

Featured

Mindfulness Leadership Software Development

Journeys and Guides and Maps

Posted on .

It's hard to draw a map of a place if you've only ever been through it once, going in a straight line in a fast moving vehicle.

For a guide, you may want someone who can draw a map from memory. You may want someone who has been lost where you're going. You may want someone who has, at least, been there a lot of times, walking in more of a zig-zag pattern and seeing what's around.

OR you're accepting a guide who knows a little more than you but can't draw the map.

Both can work, but understand what you're getting and accept the advantages of the latter if you choose it. That is, you will be getting lost along the way, but you will also be a guide at the end of the journey.

Sometimes there is no map and never will be - for the country is forever new. In these cases we can only compare it to country we have been in before and offer help to one another.

Featured

Rebuild Application Rebuild Software Development

Code is Harder to Read than Write - Part 2 - More Reasons

Posted on .

Link to Part 1.

More reasons why code is harder to read than write:

  1. Code is meant to be executed by machines, not to be read by people. In other words, you, as a human, are not the intended audience. Everything about the program you're trying to read, including the intent of the language designers, was focused on machines and not on you.
  2. Developers don't get paid to write, they get paid to build.
  3. Developers prefer to build things over writing about it or adding comments to code.
  4. There is always a deadline. The deadline is never about writing comments or documentation.
Featured

Rebuild Application Rebuild Software Development Software

Code is Still Harder to Read than Write - Part 1

Posted on .

I've posted this article recently, but it got me thinking about why code is harder to read than to write. So, I will post it again, to make your life easier and explain why I think that code is still harder to read than write, even all these years later. Here's the article:

Things You Should Never Do, Part 1

The title of this post seems counter-intuitive because we think of reading and writing in relationship to human language, but programming languages are not like human language.

What are the important differences? Here is the main one:

Programming languages can't be read aloud.

So when we talk about 'reading code' we're using 'reading' in a purely metaphorical sense. When you 'read' code you don't actually read it - you're looking at it and trying to make sense of what it does.

This is nothing like reading a book, paragraph, or sentence written in human language.

When you review code you study, you re-read, you look things up. You jump around from file to file. You may consult web pages. Even in programming languages you are familiar with and with a business domain you know, these tasks can be time consuming.

You're trying to 'read' something that can't be read, across many files, and trying to ascertain the author's intent not just comprehend a sentence.

An equivalent would be trying to read in a language where you had to look up every third word, every time you read something because:

  1. Every author used the language in a novel way. AND
  2. Every page of a book was put in a different file and they were constantly referencing each other and not in order.

It would be hard. And it would not really be reading. That's what 'reading' code is.