Home on Technically Writing

Documentation-first programming: what it means for technical writers

Mon, 25 May 2026 09:00:00 +0200

A familiar argument, now heard in the right room

I recently read an interesting article called Documentation-first programming on the Negroni Venture Studios website. The central argument of the post, which has been doing the rounds in tech writing circles, is simple and, for anyone who has worked in technical writing, it probably rings a bell: the specification is the program. The code is a disposable byproduct.

The author, Alasdair Allan, came to this conclusion by building a programming language designed for machines to write. Every function requires a formal contract: what it needs, what it guarantees, what effects it performs. The compiler proves these contracts hold. No variable names, no style choices, one canonical form. And what does the human write? Contracts. Specifications. Documentation.

Why HTML beats PDF for hardware tech docs

Wed, 29 Apr 2026 12:00:00 +0200

I recently attended the Information Energy 2026 virtual conference, which focuses on content strategy and technical communication. Like most tech writing events right now, AI was a dominant theme - how to write for it, how to use it, how to prepare your content for it. All useful and valuable stuff.

But one talk stood out to me for a different reason, and it wasn’t really about AI at all. It was about a problem I’m dealing with right now at work.

About

Tue, 17 Mar 2026 00:00:00 +0000

My name’s Ian and I’m a technical writer based in Spain working mainly on software documentation.

I started out my career in the tech support world, moved into journalism, followed that with a stint in digital project management and I eventually ended up doing what I feel is my true vocation - technical writing!

I’ve been writing for many years now about all sorts of topics but I really began to focus on technology in 2015 when I started working for a startup. Technology is a topic that’s always fascinated me and I feel lucky to work in a sector where I can learn something new every day.

Don't panic: a tech writer's guide to the agentic-verse

Fri, 13 Mar 2026 00:00:00 +0000

Introduction

Douglas Adams’s seminal work The Hitchhiker’s Guide to the Galaxy is, among many other things, a meditation on how to navigate complexity with limited information and imperfect tools. This is probably a familiar-sounding situation for technical writers - explaining complex systems to audiences with varying levels of expertise and using tooling that is not always designed for managing documentation.

And if you’re a technical writer coming across agentic AI for the first time, you might be feeling a bit like the novel’s protagonist Arthur Dent, suddenly thrust into a universe of possibilities that can be both exciting and overwhelming. I hadn’t read HHGTTG since I was a youngster, but it’s well worth revisiting - not just for its absurd and acerbic humour, and fantastic imagination, but also for the way it captures the spirit of a guide: a resource that is useful and approachable. It’s a love letter to the idea of a guide.

How AI is changing collaboration between docs and support

Sun, 01 Feb 2026 00:00:00 +0000

Overview

Technical writers and support teams have always worked closely together, but I think that the rise of AI is fundamentally changing how we collaborate, close documentation gaps and ensure that we provide users with the information they need, when they need it. With the increasing adoption of automation and large language models (LLMs) in technical writing, we’re seeing new workflows emerge - some promising, some still rough around the edges.

Beyond documentation: tech writers as strategic enablers

Wed, 17 Dec 2025 12:28:51 +0200

Overview

The recent Write the Docs Berlin conference led me to reflect on the evolving role of technical writers. Here are some thoughts on how I think the technical writer role is evolving into one of “strategic product enabler” and why this transformation matters for organizations.

We’re everywhere

We’re everywhere: in your code, in your applications, in your APIs. We’re quality control. We’re project managers. We’re user advocates, trainers, strategists, designers, maintainers, collaborators, problem solvers and educators.

Write the Docs Berlin 2025

Wed, 12 Nov 2025 12:28:51 +0200

Overview

I gave a talk at the recent Write the Docs Berlin 2025 conference. For those of you not familiar with Write the Docs, it’s a global community of people who care about documentation. They have regular conferences in different locations around the world. It was a fantastic event with a very diverse lineup of speakers and attendees. I really enjoyed the experience.

I had previously spoken at Write the Docs Atlantic in 2023 where I talked about terminology management, and, while I enjoyed it a lot, it was a virtual event and I did miss the in-person interaction a little bit.

CV

Fri, 17 Oct 2025 09:09:16 +0200

Check out my LinkedIn page to see where I’ve worked.

Writing samples

Here are just a few things I’ve worked on and written over the years:

Technical documentation

Salto Systems Support Portal: https://support.saltosystems.com/
Salto Systems Developer Portal: https://developer.saltosystems.com/
Kolibri User Guide: https://kolibri.readthedocs.io/en/latest/
Kolibri Developer Documentation: https://kolibri-dev.readthedocs.io/en/develop/

Technology

Venturebeat: How AI will change the way we live
IoT News: KITT is no longer a fantasy: Assessing the rise in infotainment for connected cars
Forvo: Accelerated Mobile Pages - one of many posts I contributed to at Forvo
Forvo Releases New Pronunciation App for Android Phones - press release

Food and drink

Spain Gourmetour: Sparkling Aspirations - article about Cava (Page 40)
Spain Gourmetour: Various articles about Spanish cuisine

Other

Hello! Magazine: Worked as editor of the website: https://www.hellomagazine.com/

Technologies, tools and other things I’m familiar with

Languages and frameworks

Go
gRPC
Javascript/Typescript
Angular
Hugo
HTML
CSS
Markdown

Tooling

Git
GitHub/GitLab
Command line (Bash/Zsh)
CI/CD
Linters (for example, Vale, markdownlint, etc.)
IDEs: Visual Studio Code
GitHub Copilot

Design

Adobe Creative Suite (Photoshop, Illustrator, InDesign, Premiere)
Sketch
Figma
UX writing
Content design

General

API/SDK documentation and developer portals
Web development
Mobile app development
Internet of Things (IoT)
Jamstack
Netlify
Google Cloud Platform (GCP)
Project management

Open source

You can see some of the open source projects I’ve contributed to in this blog post about open source.

AI the Docs 2025 conference

Sat, 12 Jul 2025 12:28:51 +0200

Event overview

I recently attended the AI the Docs event which focused on the intersection of artificial intelligence and technical documentation, exploring how AI is transforming documentation creation, consumption, and management. The event took place over two days with multiple speakers and presentations.

This blog post summarizes the key themes, notable presentations, and practical recommendations from the event. I’ve used the LLM Claude Sonnet 3.7 to parse my raw notes and help me write this summary.

TechDocsCon at Open Source Summit Europe

Tue, 12 Nov 2024 12:28:51 +0200

I recently attended Open Source Summit Europe 2024. It’s an event organized by the Linux Foundation, and although the main focus is on the development of open-source software, there was a good deal of documentation-related presentations and discussion.

It was also the first TechDocsCon track at Open Source Summit Europe, and I was really happy to see a micro-conference dedicated to documentation at such a big and well-attended event.

Main conference

Before going into the details of TechDocsCon, here are some documentation-related highlights from the main conference.

Book review of 'Docs-as-Ecosystem'

Tue, 03 Sep 2024 12:28:51 +0200

A review of the book Docs-as-Ecosystem by Alejandra Quetzalli.

Talking terminology at Write the Docs Atlantic

Thu, 26 Oct 2023 12:28:51 +0200

I gave a talk at the recent Write the Docs Atlantic conference.

For those of you not familiar with Write the Docs, it’s a global community of people who care about documentation.

My talk was about glossaries and managing terminology at scale. You can see an abstract of the talk on the conference speakers page.

The experience was great and I really enjoyed the Q&A session after the talk. People had a lot of questions and it was really nice to see how everyone had engaged in the talk.

Participating in Google Season of Docs

Tue, 08 Feb 2022 12:28:51 +0200

I participated in the 2021 edition of Google Season of Docs (GSoD) working with the organisation Learning Equality.

Source: developers.google.com/season-of-docs

GSoD is an initiative that provides support for open source projects to improve their documentation and gives professional technical writers an opportunity to gain experience in open source.

The project involved supporting the internationalisation and localisation processes of Kolibri, Learning Equality’s end-to-end suite of open-source software designed for offline-first teaching and learning.

Naming things is hard

Thu, 14 Jan 2021 12:28:51 +0200

There are only two hard things in Computer Science: cache invalidation and naming things.

– Phil Karlton

Contributing to open source projects

Wed, 11 Nov 2020 12:28:51 +0200

My limited experience of contributing to open source projects as a technical writer has been a lot of fun so far.

Docs-as-code resources

Tue, 15 Sep 2020 12:28:51 +0200

When I first started out on my technical writing journey, one of the main concepts I kept reading about was “docs as code”, or “docs like code”.

Code itself had always seemed like a bit of a mystery to me, so what was treating documentation as code all about? How did it differ from “normal” documentation and why would anyone want to treat documentation as code?

You've Git to be kidding me!

Mon, 20 Jul 2020 15:09:39 +0200

As a lone writer who had to get to grips with Git when I started a new role in early 2019, I have to say there’s definitely a steep learning curve to it.