Writing by Peter Hilton


#software #product #DDD #data #design #API #NoCode #agile #documentation #book #maintenance #naming #programming #comments

Forge Wood to Gatwick

How to walk to London Gatwick Airport (LGW) 2022-08-09 #travel

The reverse agenda

How to reclaim agency and avoid pointless meetings 2022-08-02 #collaboration

The hybrid-remote delusion

Hybrid-remote means many things other than actually remote 2022-07-26 #remote

Executive training for remote work

Announcing a series of hands-on courses for the modern workplace 2022-07-19 #remote

Reserve weekly time for writing

Keep writing, even when you don’t know what to say 2022-07-12 #writing

Conference expectations

What speakers can expect from conference organisers 2022-07-05 #conferences

Brute-force modelling

When avoiding over-modelling feels like cheating 2022-06-28 #DDD

The importance of programming jokes

Domain-specific jokes’ purpose 2022-06-21 #programming #DDD

Domain-specific languages go digital

Alternative names for ‘domain-specific language’ (DSL) 2022-06-14 #programming

Modelling multitudes

Measuring, counting and naming different kinds of quantities 2022-06-07 #data #design #DDD

Truncate content according to context

When omitting the end of text that doesn’t fit doesn’t work 2022-05-31 #design

Mac OS System 7 outlines vs HTML

Tree views on the web 2022-05-24 #design

Mac OS System 7 inputs vs HTML

Browser-native user-interface controls compared to Mac OS 31 years ago 2022-05-17 #design

Mac OS System 7 menus vs HTML

Browser-native user-interface controls compared to Mac OS 31 years ago 2022-05-10 #design

Mac OS System 7 buttons vs HTML

Browser-native user-interface controls compared to Mac OS 31 years ago 2022-05-03 #design

Use high-contrast text

The dark side of grey text 2022-04-26 #design

Guide user input

How to fix, hint, and validate before complaining 2022-04-19 #design

Use a money data type

Why your software should handle money amounts separately from other numbers 2022-04-12 #software #data #design #DDD

The right tempo for renaissance polyphony

How fast to sing sixteenth century church music 2022-04-05 #music

Modelling numeric values

More than just size and precision 2022-03-29 #design #DDD

Show content without elision

When perceived cleanliness trumps user experience 2022-03-22 #design

How to talk to developers

Boring meetings and balanced conversations 2022-03-15 #product

Use a currency-specific number of decimals

Why a money amount isn’t just a number 2022-03-08 #software #data #design #DDD

Reduce scope at different scales

Why software development requires reducing scope at every step 2022-03-01 #agile #product

Continuously reduce scope

Why product development requires repeated scope reduction 2022-02-22 #agile #product

Build a separate API for public consumption

Because APIs have user personas too 2022-02-15 #API #design

The cost of a free API

How you pay for publishing your back-end’s API 2022-02-08 #API #design

Populate country lists carefully

How to source a list of countries to use in software 2022-02-01 #software #data #design #DDD

Localise names with the CLDR

Using the Unicode Common Locale Data Repository’s standard translations 2022-01-25 #software #data #design #DDD

Internationalise data

Better software through commoditised domain modelling 2022-01-18 #software #data #design #DDD

Default to the browser’s preferred language

Don’t set the web page language based on location 2022-01-11 #software #design

CSV isn’t broken - Excel is broken

Reasons to blame Excel for comma-separated values (CSV) issues 2022-01-04 #data

2021 startup company ideas

Another year, more free ideas 2021-12-30 #startups

Publish data using the CSVW standard

Use W3C’s ‘CSV on the Web’ (CSVW) standard to make data accessible 2021-12-28 #software #data #design

Create RFC 4180-compliant CSV files

How to solve the worst comma-separated values (CSV) problems 2021-12-23 #software #data #design

Why CSV survives

The enduring nature of comma-separated values (CSV) 2021-12-21 #data

CSV character encoding

Comma-separated values (CSV) with the wrong characters 2021-12-14 #data

CSV delimiter confusion

Comma-separated values (CSV) files don’t always use commas 2021-12-07 #data

Jargon-centric naming

Restricting names to controlled vocabularies 2021-11-30 #naming #DDD

The death of the living document

Relics of the typewriter age 2021-11-23 #documentation

Weblog throwback

Blogging like it’s 2001 2021-11-16 #links

Domain primers

How software developers and product people can bootstrap subject-matter knowledge 2021-11-09 #DDD

Collect writing ideas

How to find ideas to write about instead of planning them 2021-11-02 #writing

Get yourself a notebook

The first step towards regularly having something to blog about 2021-10-26 #writing

IBAN support for no-code platforms

International Bank Account Numbers and data type design decisions 2021-10-19 #NoCode

Pluralise text correctly

User-interface content design details matter too 2021-10-12 #software #design

Good manager/bad manager

Choices that managers make and you can too 2021-10-05 #management

No code but not no maintenance

Software maintenance with no-code tools 2021-09-28 #NoCode

Scrum and non-functional requirements

The qualities you must not ignore 2021-09-21 #agile

Web-based online whiteboards

Essential tooling for remote teams 2021-09-14 #agile #remote

Lots of whiteboards

Classic product development hardware 2021-09-07 #agile

No-code solution complexity

‘No-code’ doesn’t mean simplistic 2021-08-31 #NoCode

Lean coffee on-site for remote teams

A flexible in-person activity for a distributed team 2021-08-24 #remote

City walking tour team event

A flexible in-person activity for a distributed team 2021-08-17 #remote

Working remote on hard mode

The value of regularly meeting in-person 2021-08-10 #remote

HTTP API versioning approaches

Why the experts say you shouldn’t 2021-08-04 #API #design

Write better code

Learning how to become a better coder 2021-07-27 #programming

Book review: The Art of Logic

A case study in the importance of good examples, by @DrEugeniaCheng 2021-07-20 #book

Documentation planning

A checklist of questions to de-risk software documentation efforts 2021-07-16 #documentation

Living glossaries and data dictionaries

Reflections on ‘Living Documentation’, by @cyriux 2021-07-06 #documentation #book

Domain-driven development

Why no-code tools enable ultimate domain-driven design 2021-06-29 #NoCode #DDD

Curation and storytelling for software documentation

Reflections on ‘Living Documentation’, by @cyriux 2021-06-22 #documentation #book

Apologetic error messages

Following through on a naming idea by @huizendveld 2021-06-15 #naming #programming

Knowledge augmentation and technical writing

Reflections on ‘Living Documentation’, by @cyriux 2021-06-09 #documentation #book

Knowledge exploration and exploitation

Reflections on ‘Living Documentation’, by @cyriux 2021-06-01 #documentation #book

Principles of living documentation

Reflections on ‘Living Documentation’, by @cyriux 2021-05-25 #documentation #book

Martraire’s principles of documentation

Reflections on ‘Living Documentation’, by @cyriux 2021-05-18 #documentation #book

Use skin tone emoji that match your skin

The missing help page for white @SlackHQ users 2021-05-11 #learning

Content before style and structure

How no-code tools let you start simple and avoid up-front design 2021-05-04 #NoCode

Form builder value styles

Word processor paragraph styles as no-code custom data types 2021-04-27 #NoCode

Talk about programming

Learning how to become a better coder 2021-04-20 #learning

Talk about technical books

Learning how to become a better software/product developer/manager 2021-04-13 #books #learning

Read technical books

Learning how to become a better software/product developer/manager 2021-04-06 #books #learning

Flow charts and pseudocode

Why non-executable process models don’t work 2021-03-30 #NoCode

What to put in a README

How to minimally document software 2021-03-23 #software #documentation

Capturing what’s in your head

The decision-making tacit knowledge problem 2021-03-17 #NoCode

HTTP client error status code checklist

Because HTTP API clients don’t just send bad requests 2021-03-09 #API #design

Technical writing - my first ten years

Posts on the @LunatechLabs tech blog, 2005-2014 2021-03-02 #writing

Allow varied national telephone number formats

Why telephone numbers don’t add up 2021-02-23 #software #data #design #DDD

Respect people’s full names

Don’t call someone’s name ‘invalid’ 2021-02-16 #software #data #design #DDD

Use HTTP error handling in APIs

Improving developer experience with a richer HTTP vocabulary 2021-02-12 #API #design

Book review: Succeeding with OKRs in Agile

A practical guide for agile software development practitioners, by @allankellynet 2021-02-09 #product #book

Forgive user input in the wrong format

Don’t make people normalise data manually 2021-02-02 #software #design

Omit salutations in automated notifications

Don’t waste time on fake greetings 2021-01-26 #software #design

HTTP API documentation mistakes

Five common ways to get stuck writing the docs 2021-01-19 #product #API #documentation

Build unisex software

Don’t ask people to tell you their gender 2021-01-13 #software #design #DDD

Deconstructed HTTP API documentation

The conventional way to write hard-to-use API documentation 2021-01-07 #product #API #documentation

Implement a zero-bug policy

How to manage bugs during software product development 2021-01-05 #software #product

2020 startup company ideas

Another year, more free ideas 2020-12-29 #startups

Six fears of public speaking

How to opt out of things that stop you proposing talks 2020-12-22 #speaking

Facing fear of public speaking

How to get used to the idea of your first presentation 2020-12-15 #speaking

Development environment documentation

Essential software product documentation for the development team 2020-12-08 #product #documentation

Validate email addresses to level 4

First person to say ‘regex’ loses 2020-12-01 #software #data #design #DDD

Why developers write bad API documentation

Coding habits that hinder technical writing 2020-11-24 #product #API #documentation

Allow all printable characters

First person to say ‘special characters’ loses 2020-11-17 #software #data #design

The API documentation usability problem

Why API documentation tends towards a poor developer experience 2020-11-10 #product #API #documentation

Use localised language names for language selection

Don’t use flags for languages 2020-11-03 #software #design

Product owner unavailable

Making Scrum work despite patchy product owner availability 2020-10-27 #agile

Sort every collection you display

Unsorted is never the right order 2020-10-20 #software #design

Book review: Epic Alignment

How to write structured feature documents 2020-10-13 #product #book

Refactor Boolean values to enumerations

From ‘97 Things Every Java Programmer Should Know’ 2020-10-07 #programming #DDD

Numbers that aren’t numbers

‘Numbers’ that you can’t represent numerically 2020-09-29 #software #data #design #DDD

Source code layout

Why source code deserves layout as well as typography 2020-09-22 #programming

Ugly code and typography

Why good code still looks bad 60 years on 2020-09-15 #programming

Get better at naming things

From ‘97 Things Every Java Programmer Should Know’ 2020-09-08 #programming #DDD

No-code and no testing environments

Testing no-code automation presents a hard problem 2020-09-02 #NoCode

Software’s process value

Why special-purpose software offers more than its functionality 2020-08-25 #product

What has ‘no code’ ever done for us?

Why you shouldn’t dismiss imperfect solutions 2020-08-19 #NoCode

Write one-sentence documentation comments

From ‘97 Things Every Java Programmer Should Know’ 2020-08-11 #programming

No-code automation’s non-violent revolution

The enterprise IT transformation that you might not notice 2020-08-05 #NoCode

More inane start-up ideas

Yet more free ideas from the archives, 2018-2019 2020-07-28 #startups

We need to talk about ‘no code’

Why ‘no-code automation’ needs a better name 2020-07-21 #NoCode

Learning to ski - starting agility with Scrum

Why basic techniques have their place 2020-07-14 #agile

Why no-code automation’s innovation isn’t functionality

It’s the user experience, stupid 2020-07-07 #NoCode

Software review: Shipright

A single source of truth for your customers’ product feedback 2020-07-01 #product #software

Three principles for remote meetings that work

How to discover specific guidelines and practices for your situation 2020-06-23 #remote

Automation without the secret codes

How no-code automation modernises programming 2020-06-16 #NoCode

Writing with a word count limit

The enabling constraint of a strict 450-550 word limit 2020-06-09 #writing

Time zone compromises

Winning against time zones in software by not actually fighting 2020-06-03 #product

First look: Dark

A new back-end language and #nobuild web-based development environment 2020-05-26 #programming

Software review: Delibr

Structured writing for feature documents 2020-05-19 #product #software

Product backlog naming tips

How to name things, for product people 2020-05-12 #product

Naming products isn’t the problem

Why product backlog item naming matters 2020-05-05 #product

The product roadmap triangle

How to make trade-offs between roadmap qualities 2020-04-28 #product

Roadmaps in two dimensions and three levels

How to relate your roadmap to what matters 2020-04-21 #product

Your product roadmap is a compromise

Finding a balance between flexibility and transparency 2020-04-14 #product

Software review: productboard (roadmaps)

Sharing product roadmaps in @productboard 2020-04-07 #product #software

Software review: productboard (insights board)

Capturing customer feedback in @productboard 2020-03-31 #product #software

Software review: productboard (features board)

Managing a product backlog in @productboard 2020-03-25 #product #software

Book review: Choose Your First Product

How to find and validate a product idea, by Leon Bambrick (@secretGeek) 2020-03-18 #product #book

Book review: The Art of Agile Product Ownership

How to understand the best way to fulfil the PO role, by @allankellynet 2020-03-12 #product #book

The good kind of legacy code

A supply chain software maintenance project story from 2012 2020-03-04 #maintenance

The worst kind of legacy code

A supply chain software maintenance project story from 2006 2020-02-25 #maintenance

Extensive technical documentation

An asset management software maintenance project story from 1997 2020-02-19 #maintenance #documentation

Visit your customers and ask them questions

How to get them talking about your product’s value proposition 2020-02-11 #product

Book review: Continuous Digital

How to merge software business with software development, by @allankellynet 2020-02-04 #book

Identify your product value proposition

Why people will buy your product 2020-01-29 #product

Deliver a 3-5 point product-pitch

How to build initial product marketing from a product definition 2020-01-21 #product

Define your product using existing product categories

How categories clarify your product definition 2020-01-15 #product

Write a three-part product definition

How to set the context for your product story 2020-01-08 #product

Articulate the minimal product definition

How to set the context for your product in one sentence 2020-01-02 #product

Book review: Project Myopia

What’s wrong with software development projects, by @allankellynet 2018-09-17 #book

How to write unmaintainable code

Tribute to the classic thesis by Roedy Green 2018-09-04 #code #maintenance

Three causes of unmaintainable code

Why programmers are lazy and too clever for their own good 2018-08-20 #code #maintenance

Language expressiveness versus code maintainability

How different programming languages lead to different software maintenance challenges 2018-08-13 #code #maintenance

Start-up ideas are still cheap

More free ideas from the archives, 2015-2017 2018-07-27 #startups

Start-up ideas for software development

Things you wish your favourite IDE vendor would invent 2018-07-16 #startups

Software maintenance’s terrible question

The big question that teams don’t ask about software products 2018-07-09 #code #maintenance

Start-up ideas for apps

Apps that someone else is going to sell if you don’t 2018-06-29 #startups

The code maintenance problem

Why software maintenance is worth talking about 2018-06-26 #code #maintenance

Ligatures with Fira Code

The coding font with ligatures that not everyone knows about 2018-06-15 #code #typography

Correlation IDs for microservices architectures

Sorting out logs with UUID, GUID, CUID and other identifiers 2017-07-12 #microservices

Single-letter names - a cautionary tale

Phillip Relf’s story of two lazy array index names 2017-01-10 #naming #programming

Paper review: Achieving Software Quality through Source Code Readability

A computer science paper reviewed from an industry perspective 2016-12-31 #naming, #readability, #paper

What science says about naming

Computer science papers about naming (co-written with Felienne Hermans) 2016-12-26 #naming #programming

How to get better at naming things

10 steps to mastering names in code 2016-11-20 #naming #programming

Naming smells

Code smells that indicate bad names so you can avoid using them 2016-10-31 #naming #programming

Why naming things is hard

The hardest thing in programming and the great naming myth 2016-10-22 #naming #programming

Where to start documenting a legacy system

What new team members need, to understand a system 2016-09-30 #documentation

10 things programmers will switch jobs for

When they’re ready to leave, here’s what they’re looking for 2016-05-09 #recruitment

Constructive laziness

Creative productivity for programmers 2016-03-28 #programming #documentation

Questions about documentation and avoiding writing it

Q&A for my forthcoming keynote at ProgSCon London 2016 2016-02-08 #documentation

Book review: Functional Programming in Java

by Pierre-Yves Saumont - FP unencumbered by libraries, standard or otherwise 2016-01-29 #programming #book

Legacy code

One programmer’s meat is another programmer’s poison 2015-11-28 #programming

Not talking to programmers

Why face-to-face communication isn’t as good as they say 2015-11-20 #programming #documentation

Book review: Functional Reactive Programming

by Stephen Blackheath and Anthony Jones - Intelligent, clear and witty 2015-10-26 #programming #book

My documentation problem

ACCU 2015 lightning talk script 2015-04-24 #documentation

BPM as a preferred approach to business application development

The fundamental problem with a process-centric approach 2015-03-16 #BPM

Permission to enjoy process modelling

How to indulge in making process models 2015-03-12 #BPM

The process modelling trap

Why you can’t help obsessing over diagrams 2015-03-08 #BPM

The zero-code delusion and its silver lining

The hidden value of disguised programming 2015-02-25 #BPM


why JavaScript frameworks live short but happy lives 2015-02-12 #JavaScript #naming

Processes are not set in stone

process management means embracing change 2015-02-09 #BPM

camunda BPM with Play and Scala

integrating Business Process Management with a web application 2015-01-27 #BPM #playframework #Scala

camunda developer-friendly BPM

a Business Process Management platform by and for developers 2015-01-22 #BPM

What to write on Twitter

the most important part of how to use Twitter 2015-01-19 #Twitter

Networking tips for conference organisers

how to help attendees connect with each other 2015-01-12 #conferences

Small details for conference organisers

Inspiration for incremental improvements 2015-01-05 #conferences

Presentation tips for conference organisers

How to help speakers deliver legible slides 2014-12-30 #conferences

Start-up company ideas are cheap

A good team that executes well matters most 2014-12-26 #startups

Supplier Rejection Management

Building interruption marketing countermeasures with @Twilio 2014-11-26 #vapourware

Comments are the introduction

three ways to introduce code 2014-11-03 #programming #comments

One Big Menu

Unbundling restaurant menus on the web 2014-10-21 #vapourware

How to comment code

What you have to actually do to get good comments 2014-10-09 #programming #comments

3 kinds of good comments

Code tells you what and how - you need comments to say why 2014-10-08 #programming #comments

7 ways to write bad comments

Things you don’t want to do to your code 2014-10-07 #programming #comments

On the origin of systems thinking

John Seddon is this week’s mandatory viewing 2014-10-03 #management

Systems integration with Effektif

Using JavaScript tasks to access web services 2014-09-24 #BPM

Custom development with Effektif

What a process-centric spreadsheet alternative means for developers 2014-09-23 #BPM

Effektif hosted BPM

A different kind of business automation 2014-09-22 #BPM

Fear of renaming

Why renaming is harder than naming 2014-09-17 #programming #naming

Meaningless variable names

Naming things without actually choosing a name 2014-09-04 #programming #naming

Software development quotations

My favourite insights from articulate programmers; send me yours! 2014-09-03 #programming

Camel message processing using the Scala DSL

A new Typesafe Activator template 2014-09-01 #Camel #Scala

Camel HTTP file upload with multipart/form-data

How to integrate with legacy HTTP endpoints 2014-08-29 #Camel #Scala

Inspecting HTTP client requests

Four easy tools for debugging web services 2014-08-28 #programming

Software estimation checklist

Ten ways to avoid bad estimates 2014-08-26 #agile

How to seduce a writer

Neil Gaiman doesn’t always write about programming 2014-08-22

Scrum user story chilli ratings

Hotter than t-shirt sizes, looser than dress sizes 2014-08-21 #agile

Neil Gaiman’s rules for coding

@neilhimself writes about programming 2014-08-20 #programming

Post-it Super Sticky - notes that don’t fall off

Scrum hardware innovation (via @vgrgic) and Correct Post-it Technique 2014-08-19 #agile

George Orwell’s six rules for Scala programmers

A concise style guide 2014-08-18 #Scala

Talking about the cost of delay

Another way to look at business value 2014-08-15 #agile

Source code maximum line length

GitHub sets the standard for code reviews 2014-08-14 #Scala

Development cost is relative to value

Putting effort estimates in perspective 2014-08-13 #agile

Play/Slick back-end for jQuery UI Sortable

A new Typesafe Activator template 2014-08-12 #Scala

Today I learned useful and weird stuff

Working out loud and social learning 2014-08-11 #collaboration

Formatting Clojure source code

The one thing that emacs can’t do 2014-08-08 #Clojure

Process-centric application design

The fourth way to think about the problem 2014-08-07 #BPM

Things the Scala compiler doesn’t do

Impossible functionality that you don’t actually want 2014-08-06 #Scala

Scaling down Play and Scala web applications

Cruising with Play, Scala and in style 2014-08-05 #Scala

Architect - the missing Scrum role

Agile architecture for non-functional requirements 2014-08-04 #agile

What’s missing from the Scala Style Guide

Input for team-specific code conventions 2014-08-01 #Scala

Agile user modelling with TV character personas

Better-looking software requirements analysis 2014-07-31 #agile

Dropping the ‘agile’ from ‘software development’

Why ‘agile’ is still the new name for methodology 2014-07-30 #agile

Code comments and metaphysical subjectivism

The philosophy of software maintenance and the objective meaning of legacy code 2014-07-29 #programming #comments

Learning another programming language

The second language is hardest 2014-07-28 #programming

Arithmetic symbols in source code

Why ASCII’s fifty year-old legacy is still with us 2014-07-25 #programming

Simple processes need case workers too

Reducing errors with end-to-end responsibility 2014-07-24 #BPM

What is a collaboration platform?

Collaboration is a tag - not a category 2014-07-23 #collaboration #product

Supply chain delivery performance improvements

How status updates can improve perceived performance 2014-07-22 #supplychain

Using only English words in code

What if you could tell the compiler to require correct spelling? 2014-07-21 #programming

Object-oriented programming with constrained types

What if you had to define types for all values? 2014-07-17 #programming

Enforcing coding style as part of the language

What if the compiler only accepted one coding style? 2014-07-16 #programming

Does @SavedYouAClick prove Betteridge’s Law?

A brief study of clickbait headlines 2014-07-14 #socialmedia

Older articles (2005-2014)

172 articles from mid-2005 to mid-2014 are published on the Lunatech Blog.

97 Things Every Java Programmer Should Know

book cover

97 Things Every Java Programmer Should Know edited by Kevlin Henney, Trisha Gee, with contributions by Peter Hilton, published by O’Reilly Media in May 2020.

Play for Scala

Play for Scala by Peter Hilton, Erik Bakker and Francisco Canedo was published by Manning Publications in September 2013. The book teaches web developers how to use the Play Framework to build web applications using the Scala programming language.

Peter Hilton presented widely on the topic and was a certified trainer for Typesafe’s Fast Track to Play with Scala training course, before they rebranded as Lightbend.

Other people’s writing

Theatrical Adventures - Musings and memories of a thespian, by O.B. Clarence

Poetry by C R Hilton

Tristan And Iseult: A Jungian Interpretation

Cafe reviews (2000-2012)

Independent cafe and restaurant reviews, from before TripAdvisor was invented:

🇳🇱 Rotterdam, Maastricht, Amsterdam, Delft

🇨🇦 Kitchener-Waterloo

🇪🇸 Madrid

🏴󠁧󠁢󠁥󠁮󠁧󠁿 Cambridge, Oxford, London

🇮🇹 Florence

🇧🇪 Leuven, Antwerp

🇫🇷 Paris, Hyères

🇮🇪 Galway

🇱🇺 Luxembourg

🇦🇹 Vienna

Older articles (1996-2004)

Travel writing

Cambridge Coffee & Cake Guide
Cambridge Restaurant Reviews
Diary Of An International Assignment (Luxembourg)
European Café Watch
Everything You Always Wanted To Know About Bordeaux
Seven Hours In Budapest


Computer books - how to choose them
Lime - an editor for online HTML publishing
Machine translation of the World Wide Web
Navigation bar links - how to generate them
Photograph thumbnails - how to make them
Web Page Design Principles
Web site architecture
Why I hate computers

Practical stuff

Cunning Cryptic Crossword Clues
Rotterdam Cycle Routes
European phrase book
Handy tips
Luxembourgish verb table
My magnificent midnight munchies
Rough & ready rapid rapid recipes


Book reviews - short reviews of computer books
Car ownership
The Critical Camera
Film reviews - tiny reviews of films I was watching
H-graph FAQ
Important Questions
Code Complete book review
Spare ideas
Why every cafe needs a sofa
Why obscure languages are more fun to learn
What 'What Numbers Could Not Be', by Paul Benacerraf, Is


Algonquin Provincial Park, Canada
Cafes On The Inside
Cafes On The Outside
Luxembourg (city)
public transport


Page index

Photo index