Thursday, November 28, 2019

How not to build code when only docs are changed (AppVeyor)

Having documentation and code in separate repositories makes sense for many projects but not for all.

When you make changes to code you want the CI process to build the code to make sure everything is ok with it. Then, once someone (or rather something) other than you have verified it's ok, it can be merged/committed.

That's all good but sometimes it can be very time-consuming.

When making a small change you can easily get frustrated if you haven't changed anything related to code.
I only fixed a typo on the readme. Why is it doing a full build?
In scenarios like this, you shouldn't be building all the code.

There are lots of reasons not to build the code but the most important is that it prevents quick, simple things from being quick and simple. The consequence of this is that if something should be quick and simple isn't people are less likely to do it (again).

I'm less likely to submit a fix for an issue in your docs if it takes hours. And yes, I count the time all the actions on the PR will take.

Fortunately, it's really simple to avoid this issue. Just configure your server to not build the code when only docs have been changed.

For my projects (built on AppVeyor) I use the following configuration to avoid building code when the only things that have changed are images (kept in the 'art directory'), anything related to docs, and/or any markdown files.

Here's the relevant snippet from my `appveyor.yml` file.

    - art/*
    - docs/*
    - '**/*.md'

I'm sure there's a similar way to do this with whatever build system/server/CI/CD process you use too.

None of those things are related to the code and so there's no need to rebuild the code to look for any accidental breaking changes or failing tests.

Log entry showing build being skipped because of the file types changed

The next thing I'd like to do with my current process is to add additional checks for documentation and validate those checks only when the affected docs are changed. But that's a task for another day...

Wednesday, November 27, 2019

Why web wrappers are a great start for Windows 10 desktop apps

As a subject that comes up regularly, I thought I'd post about this.

Remember, not all apps are the same.
They're not all created by people with the same knowledge or skills.
They're not all created with the same goals in mind.

Having a "web wrapper" (an app that is little--if anything--more than a WebView pointing to a website) can be a great option if:

  1. If all you want from the app is a way to put the same content as the website in an enclosed desktop experience.
  2. If it's a sensible business decision based on desired goals and available resources.
  3. If the decision was not made purely based on technical abilities or developer preference.
  4. If it's that or nothing.
  5. If the experience of the packaged web content is appropriately tested.
  6. If it takes advantage of running in that environment and adjusts web-based behaviors that don't make sense when running as an app.
  7. If an installable PWA wouldn't be better.
  8. If not doing it just to be able to say, "we have an app."

Tuesday, November 26, 2019

Recommended Reading: non-code related books for people creating software.

Books are great. Of course, you should read mine.
When you've read that, I recommend the following books to all software developers, even though they're not about code.

Badass: Making Users Awesome – Kathy Sierra (O’Reilly, 2015)

This is a great book about how to focus on what will make your product (app) invaluable to the people who use it. The focus isn’t on apps, but you can easily apply the lessons of this book to apps and games to help make them better. Read this book if you want to create something people will love.

Design for Hackers: Reverse Engineering Beauty – David Kadavy (John Wiley & Sons, 2011)

This is a great book full of useful, practical instructions for creating beautiful, well-designed interfaces. The focus of the book is primarily for web design and development, but it highlights fundamental principles that developers can easily apply to the UI of apps. Read this book if you’re not a designer, but would like to improve your design skills.

Elements of User Experience: User-Centered Design for the Web – Jesse James Garrett (New Riders, 2002)

This book provides an accessible introduction to the world of user experience (UX). Like many of the other books listed here, it focuses on web development but also shows how to apply what it teaches to other areas too. The book provides an overview to UX and has a structure for explaining its key components (elements). Read it if you want to learn more about the formal discipline of UX.

Rocket Surgery Made Easy: The Do-It-Yourself Guide to Finding and Fixing Usability Problems – Steve Krug (New Riders, 2009)

This is the follow-up to Steve’s earlier book, Don’t Make Me Think! The earlier book was an introduction to the importance of usability in websites; this book explains how you can run usability tests yourself. This is another book written for people developing for the web, but it’s also widely applicable to mobile app development. Read this book to learn how to begin performing your own usability testing.

The Design of Everyday Things – Donald A. Norman (MIT Press, 1988)

This book is a classic introduction to design. It’s about more than just how things look and work, as it also considers the importance of understanding how they affect the people who use them and the businesses that create them. Read this to learn more about the principles of design and how they affect everything you use and create.

Monday, November 25, 2019

Should I change my presentation style to be more like other people?

Me on stage at UnoConf 2019

I've spent a lot of time researching how to be a better presenter. The result of all of that is that I've reduced my own internal guidelines to this: don't do the bad things I see other presenters doing.

I don't like it when people read a script - So, I don't use one. (Although I do write several versions of one while preparing.)

I don't like it when people are giving a talk prepared by someone else - So I make mine my own. No-one else would give the presentation in the same way.

I don't like it when people are repeating something they've heard or researched but don't have personal experiences to share - So I only talk about things I know really well.

I don't like presentations that are given multiple times in the same way - So mine are always unique. By this, I mean, they're regularly updated and adjusted for the specific audience.

I don't like it when there's no audience interaction - So I involve the audience.

I don't like it when presenters are unprepared and underrehearsed, so they can't adjust to changes or things going wrong - So I rehearse lots.

I don't like it when people are talking about things they have no passion for--or at least don't appear to care about - So I only talk about things I can get excited about.

I don't like it when presenters take ages covering a single point - So I try and include lots of things. As a downside, this means I have a tendency to rush and may not cover items in as much detail.

I don't like it when there's no benefit to seeing a presentation live and watching a video recording would have been better. - So I encourage questions from the audience.

I know my "style" is not to everyone's taste but it feels right for me.
However, maybe I'd be more effective if I was more like other presenters...

What do you do when presenting? Or think I should do?

Friday, November 22, 2019

SimpleTesting - Get started with coded tests in .NET

tldr: I made a thing. Get the NuGet package and read more on GitHub

I have a theory: Getting started with writing coded tests is harder than it needs to be.

I wanted to make it easier to get started by getting the number of things that need to be installed or learned before it's possible to start writing tests.

The value of writing tests is better appreciated once some have actually been written, so I've made a way to put off the things you can think about later:

  • Which test framework to use
  • Which Test runners
  • What Mocking frameworks
  • What Isolation frameworks
  • What are Mocks/Stubs/Fakes and when/how should they be used
  • How to mark up tests and test classes
  • How to indicate success or failure
  • What counts as a "unit" test
  • How many, and what, different things need to be installed.

That's a lot of things to learn or be a distraction when the aim is to write tests.

My solution requires:

  • Only installing a single NuGet package.
  • No special markup needed (attributes, naming conventions, etc.)
  • Forces tests to be clear about whether they pass or fail.

To use it:

  • Have a class that inherits from `SimpleTesting.IContainSimpleTests`.
  • Have a parameterless constructor. (One is created by default if you don't add a constructor.)
  • Create public methods that return `bool` (or `Task<bool>`)
Those public methods are then "automagically" turned into tests when the code is compiled.

And it generates tests (in a different namespace to the original class) that Test Explorer picks up and can be run from within Visual Studio.

Examples of generated tests inside Test Explorer

It doesn't do everything that a full test framework does but you can use one in combination with these "simple tests."

I'd love to hear your thoughts on this?

Thursday, November 21, 2019

Make the repository public - no-one cares about your code

Just make the repository public (assuming it contains no Publicly Identifiable Information or embedded secrets.)
If it does, you should remove them anyway.

The 'make repository public' setting in GitHub

There are common fears about making code public.

  • What if someone takes it and makes something with it that they start selling or otherwise competing with my project?
  • What if someone laughs at it?
  • What if someone copies something?

So what? No-one is paying attention to what you put on-line. (If they were I doubt you'd have nothing better to do than read my blog.)

  • Use an appropriate license to address possible competition concerns.
  • Ignore the haters.
  • Assume that something will be copied.

I've heard it said many times (sorry, I can't attribute the original source) that "any code on the internet will eventually end up in production."

And if it does, that's ok. I don't feel responsible for someone else's codebase if they copy something I wrote (possibly many years) previously and use it differently without understanding the nuances and possible consequences.

Searching GitHub is now my default for working out how to use an undocumented API.

By searching for uses of the method/class/whatever, I can see how/if someone else has made it work. Not in a contrived example. But, in a real (hopefully) production code-base. If they hadn't made their code public I would have been stuck. I see making as much code as possible public as a way of paying it forward to other developers.

Seeing that an API has been used successfully by someone else (and how) is incredibly valuable and has helped unblock me from many coding challenges in the last year.
If I can make my code public and potentially help others in the future, then I'm all for it. I'm sure that the only reason someone else will look at my code is if they find it as the result of a search.

While I was sitting on the draft version of this post, I received this message.
"You can't just create a blank repo and leave me hanging!"
"Oh, no!" I thought. "This contradicts what I wrote in that (this) blog post."
I'm not sure it does, though.
This was a question about a name. The name of a repository.
(I find creating empty repositories for possible future projects cheaper than buying a domain and never doing anything with it.)

The name of the repository sparked interest, and they wanted to know more of what I intended for something with that name. (Hopefully, this suggests it's a good name.)

However, with more than 100 public repositories in my GitHub account, I can't recall ever having a random email asking about any of the code they contain.

I think my point still stands.

Wednesday, November 20, 2019

Where's the financial value in the code I write?

tldr: this is very self-reflective and likely has no value to you. I won't be offended if you don't read further.

I don't get it.
Why are software developers paid so much? Especially when so much software is so bad?
How/Why have people paid me to write code in the past?
How can I get someone to do so again?
Especially when I write so much code for free at the moment?


I've been thinking about money and getting paid for writing code.
This isn't meant as a dig at anyone. I'm just thinking about myself.
In part, this is because I don't have a job (or any paid work at the moment.)
Another part of this is that I haven't earned any money in the last six months.
And the final part is that I know I can't keep not earning money forever.

It might seem obvious that I should just get a job.
However, due to my family situation, I can only work remotely and part-time.

I also don't know what I want to do.
Some of the things I've worked on in the past aren't as appealing anymore. Or things that people are as interested in.

The idea of "writing code to earn money" VS "earning money to write code" has been playing on my mind. Ideally, I'd like to be in a place where I can write the code I want and still earn money. Having spoken with other people, that I've been in this position before is an exception and I may need to acknowledge this past privilege and be more realistic in the future.

I'm not sure:
- Does what I do provide value? To whom?
- What (and how much) value does what I'm capable of doing provide?
- How do you put a price on something?
- Who sets market rates? What are they based on?
- What do I want to do?

I still have some time before I have to be earning some money but I'd rather not get to the point where I'm only earning enough to get by each month.

If you've got this far and happen to have something I might be well suited to and you'd be willing to pay for, please get in touch.