Writing by Peter Hilton


#software #product #NoCode #agile #documentation #maintenance #naming #programming

Internationalise data

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

Default to the browser’s preferred language

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

CSV isn’t broken - Excel is broken

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

2021 startup company ideas

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

Publish data using the CSVW standard

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

Create RFC 4180-compliant CSV files

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

Why CSV survives

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

CSV character encoding

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

CSV delimiter confusion

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

Jargon-centric naming

Restricting names to controlled vocabularies - 30 November 2021 #naming

The death of the living document

Relics of the typewriter age - 23 November 2021 #documentation

Weblog throwback

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

Domain primers

How software developers and product people can bootstrap subject-matter knowledge - 9 November 2021 #DDD

Collect writing ideas

How to find ideas to write about instead of planning them - 2 November 2021 #writing

Get yourself a notebook

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

IBAN support for no-code platforms

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

Pluralise text correctly

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

Good manager/bad manager

Choices that managers make and you can too - 5 October 2021 #management

No code but not no maintenance

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

Scrum and non-functional requirements

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

Web-based online whiteboards

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

Lots of whiteboards

Classic product development hardware - 7 September 2021 #agile

No-code solution complexity

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

Lean coffee on-site for remote teams

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

City walking tour team event

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

Working remote on hard mode

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

HTTP API versioning approaches

Why the experts say you shouldn’t - 4 August 2021 #API #design

Write better code

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

Book review: The Art of Logic

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

Documentation planning

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

Living glossaries and data dictionaries

Reflections on ‘Living Documentation’, by @cyriux - 6 July 2021 #documentation #book

Domain-driven development

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

Curation and storytelling for software documentation

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

Apologetic error messages

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

Knowledge augmentation and technical writing

Reflections on ‘Living Documentation’, by @cyriux - 9 June 2021 #documentation #book

Knowledge exploration and exploitation

Reflections on ‘Living Documentation’, by @cyriux - 1 June 2021 #documentation #book

Principles of living documentation

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

Martraire’s principles of documentation

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

Use skin tone emoji that match your skin

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

Content before style and structure

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

Form builder value styles

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

Talk about programming

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

Talk about technical books

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

Read technical books

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

Flow charts and pseudocode

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

What to put in a README

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

Capturing what’s in your head

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

HTTP client error status code checklist

Because HTTP API clients don’t just send bad requests - 9 March 2021 #API #design

Technical writing - my first ten years

Posts on the @LunatechLabs tech blog, 2005-2014 - 2 March 2021 #writing

Allow varied national telephone number formats

Why telephone numbers don’t add up - 23 February 2021 #software #design

Respect people’s full names

Don’t call someone’s name ‘invalid’ - 16 February 2021 #software #design

Use HTTP error handling in APIs

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

Book review: Succeeding with OKRs in Agile

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

Forgive user input in the wrong format

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

Omit salutations in automated notifications

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

HTTP API documentation mistakes

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

Build unisex software

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

Deconstructed HTTP API documentation

The conventional way to write hard-to-use API documentation - 7 January 2021 #product #API #documentation

Implement a zero-bug policy

How to manage bugs during software product development - 5 January 2021 #software #product

2020 startup company ideas

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

Six fears of public speaking

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

Facing fear of public speaking

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

Development environment documentation

Essential software product documentation for the development team - 8 December 2020 #product #documentation

Validate email addresses to level 4

First person to say ‘regex’ loses - 1 December 2020 #software #design

Why developers write bad API documentation

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

Allow all printable characters

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

The API documentation usability problem

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

Use localised language names for language selection

Don’t use flags for languages - 3 November 2020 #software #design

Product owner unavailable

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

Sort every collection you display

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

Book review: Epic Alignment

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

Refactor Boolean values to enumerations

From ‘97 Things Every Java Programmer Should Know’ - 7 October 2020 #programming

Numbers that aren’t numbers

‘Numbers’ that you can’t represent numerically - 29 September 2020 #software #design

Source code layout

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

Ugly code and typography

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

Get better at naming things

From ‘97 Things Every Java Programmer Should Know’ - 8 September 2020 #programming

No-code and no testing environments

Testing no-code automation presents a hard problem - 2 September 2020 #NoCode

Software’s process value

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

What has ‘no code’ ever done for us?

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

Write one-sentence documentation comments

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

No-code automation’s non-violent revolution

The enterprise IT transformation that you might not notice - 5 August 2020 #NoCode

More inane start-up ideas

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

We need to talk about ‘no code’

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

Learning to ski - starting agility with Scrum

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

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

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

Software review: Shipright

A single source of truth for your customers’ product feedback - 1 July 2020 #product #software

Three principles for remote meetings that work

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

Automation without the secret codes

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

Writing with a word count limit

The enabling constraint of a strict 450-550 word limit - 9 June 2020 #writing

Time zone compromises

Winning against time zones in software by not actually fighting - 3 June 2020 #product

First look: Dark

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

Software review: Delibr

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

Product backlog naming tips

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

Naming products isn’t the problem

Why product backlog item naming matters - 5 May 2020 #product

The product roadmap triangle

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

Roadmaps in two dimensions and three levels

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

Your product roadmap is a compromise

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

Software review: productboard (roadmaps)

Sharing product roadmaps in @productboard - 7 April 2020 #product #software

Software review: productboard (insights board)

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

Software review: productboard (features board)

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

Book review: Choose Your First Product

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

Book review: The Art of Agile Product Ownership

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

The good kind of legacy code

A supply chain software maintenance project story from 2012 - 4 March 2020 #maintenance

The worst kind of legacy code

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

Extensive technical documentation

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

Visit your customers and ask them questions

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

Book review: Continuous Digital

How to merge software business with software development, by @allankellynet - 4 February 2020 #book

Identify your product value proposition

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

Deliver a 3-5 point product-pitch

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

Define your product using existing product categories

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

Write a three-part product definition

How to set the context for your product story - 8 January 2020 #product

Articulate the minimal product definition

How to set the context for your product in one sentence - 2 January 2020 #product

Book review: Project Myopia

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

How to write unmaintainable code

Tribute to the classic thesis by Roedy Green - 4 September 2018 #code #maintenance

Three causes of unmaintainable code

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

Language expressiveness versus code maintainability

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

Start-up ideas are still cheap

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

Start-up ideas for software development

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

Software maintenance’s terrible question

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

Start-up ideas for apps

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

The code maintenance problem

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

Ligatures with Fira Code

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

Correlation IDs for microservices architectures

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

Single-letter names - a cautionary tale

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

Paper review: Achieving Software Quality through Source Code Readability

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

What science says about naming

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

How to get better at naming things

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

Naming smells

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

Why naming things is hard

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

Where to start documenting a legacy system

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

10 things programmers will switch jobs for

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

Constructive laziness

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

Questions about documentation and avoiding writing it

Q&A for my forthcoming keynote at ProgSCon London 2016 - 8 February 2016 #documentation

Book review: Functional Programming in Java

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

Legacy code

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

Not talking to programmers

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

Book review: Functional Reactive Programming

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

My documentation problem

ACCU 2015 lightning talk script - 24 April 2015 #documentation

BPM as a preferred approach to business application development

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

Permission to enjoy process modelling

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

The process modelling trap

Why you can’t help obsessing over diagrams - 8 March 2015 #BPM

The zero-code delusion and its silver lining

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


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

Processes are not set in stone

process management means embracing change - 9 February 2015 #BPM

camunda BPM with Play and Scala

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

camunda developer-friendly BPM

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

What to write on Twitter

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

Networking tips for conference organisers

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

Small details for conference organisers

Inspiration for incremental improvements - 5 January 2015 #conferences

Presentation tips for conference organisers

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

Start-up company ideas are cheap

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

Supplier Rejection Management

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

Comments are the introduction

three ways to introduce code - 3 November 2014 #programming #comments

One Big Menu

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

How to comment code

What you have to actually do to get good comments - 9 October 2014 #programming #comments

3 kinds of good comments

Code tells you what and how - you need comments to say why - 8 October 2014 #programming #comments

7 ways to write bad comments

Things you don’t want to do to your code - 7 October 2014 #programming #comments

On the origin of systems thinking

John Seddon is this week’s mandatory viewing - 3 October 2014 #management

Systems integration with Effektif

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

Custom development with Effektif

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

Effektif hosted BPM

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

Fear of renaming

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

Meaningless variable names

Naming things without actually choosing a name - 4 September 2014 #programming

Software development quotations

My favourite insights from articulate programmers; send me yours! - 3 September 2014 #programming

Camel message processing using the Scala DSL

A new Typesafe Activator template - 1 September 2014 #Camel #Scala

Camel HTTP file upload with multipart/form-data

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

Inspecting HTTP client requests

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

Software estimation checklist

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

How to seduce a writer

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

Scrum user story chilli ratings

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

Neil Gaiman’s rules for coding

@neilhimself writes about programming - 20 August 2014 #programming

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

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

George Orwell’s six rules for Scala programmers

A concise style guide - 18 August 2014 #Scala

Talking about the cost of delay

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

Source code maximum line length

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

Development cost is relative to value

Putting effort estimates in perspective - 13 August 2014 #agile

Play/Slick back-end for jQuery UI Sortable

A new Typesafe Activator template - 12 August 2014 #Scala

Today I learned useful and weird stuff

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

Formatting Clojure source code

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

Process-centric application design

The fourth way to think about the problem - 7 August 2014 #BPM

Things the Scala compiler doesn’t do

Impossible functionality that you don’t actually want - 6 August 2014 #Scala

Scaling down Play and Scala web applications

Cruising with Play, Scala and in style - 5 August 2014 #Scala

Architect - the missing Scrum role

Agile architecture for non-functional requirements - 4 August 2014 #agile

What’s missing from the Scala Style Guide

Input for team-specific code conventions - 1 August 2014 #Scala

Agile user modelling with TV character personas

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

Dropping the ‘agile’ from ‘software development’

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

Code comments and metaphysical subjectivism

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

Learning another programming language

The second language is hardest - 28 July 2014 #programming

Arithmetic symbols in source code

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

Simple processes need case workers too

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

What is a collaboration platform?

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

Supply chain delivery performance improvements

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

Using only English words in code

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

Object-oriented programming with constrained types

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

Enforcing coding style as part of the language

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

Does @SavedYouAClick prove Betteridge’s Law?

A brief study of clickbait headlines - 14 July 2014 #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.

Cafe reviews

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

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

Older articles (1996-2004)


Page index

Photo index