2018 in review

It’s been a big, small year for me. Big personally with a new job, but smaller publicly, although I’m now in a position to make more time for conferences following DDD Scotland and CodeCraftConf this year.

I’m still adjusting to agency life, but that might be because it’s been a big, amazing year for Screenmedia.

Looking at my stats, it’s good to see web dev and security are high in my logs, as that’s where this blog started, although there’s a bit more tech leadership content these days as well.

I’ve also got an account over at dev.to, which is a community of developer bloggers, and a couple of posts got some interest over there, so I’ll keep cross-posting to there, please say hi 🙂

I passed my CosmosDb exam last year, so expect to hear a bit more about that. I also have some thoughts on technical architecture and team building I want to explore further. If there’s anything else you’d like to hear about, please let me know.

I’m looking at a technical leads meetup/support group in Glasgow. More details to follow, but ping me if you want to make sure you don’t miss the details.

I’m looking forward to the new year. Thanks to all of you for reading.

Here are my highlights from 2018.

Top older posts

• https://craignicol.wordpress.com/2016/07/19/excellent-export-and-the-chrome-url-limit/
• https://craignicol.wordpress.com/2015/05/05/losing-tokens-2-factor-authentication-recovery/

Top 3 written this year (WordPress Stats):

• https://craignicol.wordpress.com/2018/01/26/new-job-welcome-to-screenmedia/
• https://craignicol.wordpress.com/2018/08/03/translations-with-react-redux-and-asp-net/
• https://craignicol.wordpress.com/2018/04/03/who-do-you-work-with/ (and the canary in the coalmine)

Top on dev.to:

• https://craignicol.wordpress.com/2018/12/19/how-i-approach-coding-challenges/
• https://craignicol.wordpress.com/2018/12/07/tribe-of-mentors-11-questions/
• https://craignicol.wordpress.com/2018/04/03/who-do-you-work-with/ (and the canary in the coalmine)

My 2017 in review

After the whirlwind of 2016, 2017 looked like a quieter year. Fewer talks, some interesting and rewarding challenges bringing a new product to market, and a chance to build and reflect on what it means to be a technical leader, to move jobs, and to be productively lazy. Although I notice there’s still a lot of interest in obscure bugs thanks to Chrome’s URL limit, and the User Experience when 2 factor authentication needs to be reset.

I’ve not had quite as many blog views as last year, but I’ve accepted I’m not here to be a blogging superstar. This is my scratchpad for the talks I want to give, and a place to share useful reminders and signposts for future me, and others. Thanks to all of you who have helped shape and refine these thoughts here, on twitter and via other channels.

I wasn’t planning a new job in 2017, but more on that next week (and many, many thanks to my twitter and LinkedIn connections on that front – I’ve been humbled), which means I have some more thoughts on the product life vs the consultancy life that I hope to share this year.

I got a few opportunities to think about applying Conway’s Law to build teams that make the right software, most notably in the Architecting Teams guided conversation I led for CodeCraft.

Looking to 2018

I’d love to keep up 2 blogs a week, playing with styles and topics, as I’ve started to do last year. I’ve got enough topics on my Trello board for a few years at that pace (including one describing the Trello board). I’ve got a new adventure, and some experiments in productivity that I’ll hopefully get more time to explore, as well as reflecting on design and the next generation.

I don’t do New Year resolutions. It’s always a bad day to start something. Always reflect, always refine. And if you leave it to New Year, you’re only giving yourself 70-odd chances to change. Why limit yourself?

Sláinte

Peer Reviews and Feedback

Peer review is an essential component of a functional team producing quality software. It allows knowledge transfer, stops obvious and sometimes not-so-obvious bugs reaching production, and it aligns everyone to process and coding standards.

In some companies, “peer review” is manager driven. The technical lead or architect reviews the code, and no-one else can. They become a bottleneck. Don’t do this.

In some companies peer review is handled asynchronously, for example by pull requests. This is great for smaller teams or time-zone distributed teams, and for code that the whole team should review (new framework added, security fixes, for example) but the cost is that it increases the cycle time by introducing a delay (which could be minutes or could be days) between code being submitted, reviewed, reworked and accepted. Unless they do optimistic merging, which I’ve already dismissed.

In some companies peer review is done by pairing. One person types, the other reviews in real time. Reviews the requirements, security, UX, coding standards. This removes the feedback loop, and encourages greater reflection on each line of code, and the wider context, because the review isn’t coming in raw.

Some companies use a mix. Pair for some, or most work, but still leave space for pull requests so that other experts can review, and feedback, and understand that feature.

But however you do it, the feedback is key. I’ve seen a few people on Twitter talk about pull requests being too late, because of the feedback loop. Once the toast is burnt, it’s useless. Which is valid, but that also suggests to me a culture where the feedback talks about the result rather than the process. “This toast is burnt” is ineffective feedback. It states a fact without providing a learning opportunity to understand how not to burn it next time. And pairing doesn’t always provide that opportunity either. What might look, when copying someone else, like an odd coding convention, might be the difference between a successful release and a crippling SQL injection attack. But you need to ask why.

Some people, especially devs, are far more comfortable asking why on their keyboard, when they can reflect themselves, and research the concepts. Equally reviewers tend to be harsher in the pseudo-anonymous situation of conversing with a code diff, than talking to someone face to face. Reviewers have got to the stage of telling me they feel guilty about comments and then apologising face-to-face, but standing by the desire to see the best possible code committed.

Yes, there are definitely problems that shouldn’t make it as far as a pull request, but if you have those problems, ask yourself why there’s such a big gap between code writing and code review, why your mentoring process didn’t pick up on that issue, if the feed on process to Dev needs its own review. My experience, if something is broken in the pull request code, it was broken before that code was written. And you need to teach that developer how to use a toaster the way the rest of the team does.

---

 

If you want to continue this discussion, there’s some great threads to follow here:

https://twitter.com/perhammer/status/832224083383291904

Code review is inherently too late for collaboration, especially if there's a power dynamic like blocking someone's next action. https://t.co/98CEPSxSUc

— Brian T. Rice (@BrianTRice) July 12, 2017

Boy it's hard to get people to take conceptual corrections at the point of a code review.

— Peter Abrahamsen (@peidran) July 12, 2017

Sense and Respond by Jeff Gothelf and Josh Seiden

Sense and Respond: How Successful Organizations Listen to Customers and Create New Products Continuously by Jeff Gothelf

My rating: 5 of 5 stars

Having read Lean UX, I was expecting a good book on how organisations could deliver projects. This book is about much more than that. The authors are coming from a point of frustration where agile delivery and Lean UX projects have failed to reach their potential because the organisations surrounding them were not supportive, so this book is about how to reshape an entire organisation to meet the challenged of the modern world, with lots of positive and negative examples, which is refreshing to see in this type of book. If you’ve ever had a strategy meeting, or ever found your project success limited by your organisation, go read this book.

Easily the best book about dysfunctional organisations and organisational change I’ve read since Peopleware.

View all my reviews

Buy on Amazon UK :

“Why Agile Works” review

Why Agile Works

Coming from an Enterprise background in a previous life, of the cascading-waterfall, multiple-signoff, change-control, duelling-project-manager variety, this was a fascinating book. 

This is a book about Agile For Enterprises. Not for the teams like mine that carved an agile garden in a world of fixed-price contracts. This is for the managers who want to know where they sit on The Maturity Model. Those who need to justify why tearing up the hierarchy is a good thing, and how to make a company, not just a silo, agile.

It’s a book about the why and some of the how.

It’s definitely worth a read if those enterprise descriptions sound familiar, or PRINCE2 matters to you. Otherwise, I’m not sure you’ll get much out of it.

How do you know when it’s time to move job?

Around 18 months ago, I decided I needed a new job. It took almost 8 months to find my current job, and I swayed between wanting to leave and wanting to stay. In the end I discovered that I was finding excuses to stay because I’d been there long enough, and made enough friends, to be scared of leaving. But the company I left was a very different company to the one I joined.

If you’re starting the new year after some time off, starting to fear going back, or having doubts about your job, have a think about these things, and see where you stand. Then decide if you want to stick or shift.

Some of these are things I’ve felt, others are ones that came up from multiple people in recruitment interviews I’ve done over the last few years.

• You don’t see yourself here in 5 years
• You have more direction than your company
• You’ve lost sight of, or respect for, the company values
• You do all your learning, and all your best work, out of the office
• The idea of doing the same thing next year fill you with dread. But it’s exactly what you expect
• You’re ready for the next step, but you can’t see where that step is.
• Your team, or your company, is shrinking, and no plans for growth are forthcoming.

What’s made you switch jobs?

My 2016 in review

2016 was a big year for me. A new job, a new house and the first full year following the John Sonmez blogging course. I got back into public speaking, with my talk about APIs, and the follow-up usable APIs guided conversation at CodeCraftConf, although I missed out on the return of DDD Scotland.

I learned a lot. About leading and mentoring teams, about recruitment, about software design, about code quality, and a lot more things that I never had to consider in previous jobs. Things I was aware of, but now I have to make decisions about.

2016 has been my best year ever on my blog in terms of views, comments and visitors, so many thanks to all of you for your time and contributions here and on social media. My most popular post this year was “Don’t take your laptop home” – I don’t know if that struck a particular chord with people about work-life balance, but I know it’s something I’ve reflected on. I also see that my 5 year old post on the “Professional Development” and “Agile Is Dead” open discussions at DDD Scotland 2011 remains popular. I don’t know which, but either of them are great topics for reflective developers to consider : What does Professional Development mean? and What is Agile?

Looking to 2017

I’m not planning anything quite as dramatic for 2017 as a new job, but I still have some thoughts to share thanks to moving from consultancy development to product development and how things which once seems essential now no longer apply.

I’m also having more of a think about Conway’s Law as friends move into new companies and I reflect on the companies I have worked with. As a technical leader who wants a flexible, resilient software architecture and a passionate, always-learning team, how much can I influence one to affect the other. I’ve got a few thoughts on this, but I’d love to hear from anyone else who’s exploring this, as I’ve got a few bigger ideas here.

And I’d love to keep up 2 blogs a week, playing with styles and topics. Exploring old and new ideas. I’ve got enough topics on my Trello board for 18 months at that pace (including one describing the Trello board). If I manage to carve out the time to do that alongside my other commitments, you’ll see it here.

I don’t do New Year resolutions. It’s always a bad day to start something. Always reflect, always refine. And if you leave it to New Year, you’re only giving yourself 70-odd chances to change. Why limit yourself?

Sláinte

Lean Coffee Retrospectives

In the comments to the previous Everyone Has A Voice post, I was asked to expand some more on the Lean Coffee Retrospective. It’s not a new idea, but it’s definitely one worth sharing in the hope that it helps others.

I first encountered the Lean Coffee format at last year’s CodeCraftConf, and read about its use as a retrospective format. We’ve used Trello’s Giphy power-up to annotate the cards, to give them some life, and to make them easier to identify. We use Trello stickers for voting, so we can identify who is voting, as it’s a great way to see who’s interested in a topic but hasn’t spoken up.

We use the STOP, START, CONTINUE format to classify what we want to talk about, and recycle the single board every week, by archiving just those columns, and copying action items to the backlog.

Is this a format you’ve tried? How did it work for you?

Embracing Agile Architecture

Good architecture can respond to new requirements.  It’s malleable where it needs to be.

A good leader trusts their team. And builds their team so they can trust them.

Architecture leads software, it defines the agility of the rest of the development, and it defines the fixed points that cannot be changed, that will always tend back to the initial conditions.

Get the architecture right. Decide as a team, and document the decisions as you go. Sometimes a decision is made on a proposition that is false. Sometimes the best solution yesterday is no longer the best solution today.

Everyone should be designing architecture of the system, and everyone should be reviewing it (pull requests on the written decision are great for capturing the discussion).

Your job as a leader is to make sure those discussions happen and are productive. Put the architecture decisions and the associated documentation next to the code, so they are as open for extensions and available for refactoring.

Democratise the architecture – get everyone to buy in, and you won’t come back to the project in 5 years and wonder when the monsters and hurricanes attacked.

Your API sucks : documentation

Your API is perfect. It just needs a little finesse on the documentation. It’s fine, just farm it out to Johnny Clueless. After all, good APIs, like all good code, is self documenting. It’s just those damn users that keep asking what you mean when you said that, or wanting to know what all the options are. They’re very demanding.

Documentation out of sync with the code

getPostcode(double opt)
This method takes returns the current longitude and latitude of the user based on the information provided by their device.

Teaching Granny to suck eggs

Bad API documentation is like bad comments, it tells you everything except what you need to know, such as the return format.

getAddressFromPostcode(string postcode)
This method takes a postcode and returns the associated address.

Be explicit

However, don’t use this as an excuse to avoid documentation. Good documentation helps users access your API without using up your time. Be explicit about options, about which standards you support, and where necessary, how you support them. Even for simple things.

This image represents an authentication call to retrieve an API token that can be used when making further calls to an API. Each of the arrows represents an email discussion where the user needed clarification. This can be simplified with the right explicit statement:

To retrieve your API token, a POST request must be made to the HTTPS URL provided, with the following key-value pairs x-www-form-urlencoded into the Body of the request:

Key                       Value

client_id              your_username

client_secret      your_password

grant_type          client_credentials

If successful, this will return a JSON body in the response. The value associated with the key access_token should be appended to all subsequent requests as described below.

The use of italics is defined appropriately, and user specific information is supplied in a format to match the documented table.