Changelog Docs: Follow-Up After Four Months

Wed, 07 Oct 2026 11:36:28 +0000

In a previous post, I tested a changelog-driven approach to documentation using a real open source project, the Trongate PHP framework.

The open questions then were:

Will the changelog stay up to date?
Will users find it useful?
Will it have an impact on the official docs, for example, shorten the lag between code change and doc update?

Results After Four Months

Answering those questions:

Yes, the changelog stayed up to date

It seems like the framework maintainers have hit on an automated workflow that works for them. Their AI assistant, Grady, has updated the changelog with each of the 17 releases since I published the previous article on June 9th, 2026, without apparent human intervention.

The only exceptions were a couple of releases in early to mid July, for which I updated the changelog manually.

A writer's gripe: while clearly timely and hopefully effortless for the maintainers, the AI is wordy. Whereas I pictured the changelog as a series of bullet points of about a line or so, the AI defaults to bullet paragraphs.

No good way to measure usability

I realized "Will users find it useful?" was an ambitious question, and I have no good way to measure that. I'm open to suggestions.

I searched for "changelog" on Trongate's forums, but none of the results were a user reaction.

No visible impact on the official docs

The latest framework release was on September 27, 2026, but the docs repo has not been updated since August 25, 2026.

A one-month documentation lag for an open source project is, I would argue, hardly mission critical. However, I think this goes toward proving my point: long, narrative documentation does not lend itself to being updated at the typical rate of change of most software projects.

Did the README hold up?

This wasn't a question four months ago, but after 17 releases, I wondered if the README I wrote in April, and which hasn't been updated since, still works.

It does.

I tested it again today, October 7, 2026, and the instructions still work, which, in my humble opinion, proves one of my other points: you want to keep the documentation primitive and deliberately not all-inclusive so that it remains reasonably accurate and future-proof, enduring multiple future releases with zero maintenance.

For example, navigating to the local Trongate installation's index page is a different experience today than it was in June. However, the instructions don't reference that page. Instead, they say to go to http://localhost/trongate/demo. A cheap writer's trick, but it works.

Changelog vs Narrative Documentation: A Real-World Test

Mon, 29 Jun 2026 22:26:22 +0000

In a previous post, I advocated for a date-based documentation approach. I later realized this already has a name: a changelog.

I shared the idea internally at work and on LinkedIn and it was met with some skepticism. The most useful feedback was, "OK, but where's the part that tells me how to use the thing?"

Some narrative is OK

To address that feedback, I conceded that a brief, narrative, "how to" README, around 500 words, alongside a changelog is acceptable.

Until that point, this was all theoretical, just my opinion versus others'.

Trongate PHP framework as test case

So I decided to put this combined approach to the test with a real-world, open-source project: the Trongate PHP framework.

Trongate is an interesting case because, similar to enterprise products, it has comprehensive documentation. Comprehensive is good, but not the fastest or easiest to update.

Trongate changes are typically committed/merged into master and released immediately. Documentation is updated soon afterward, but there is a lag.

My hypothesis is that maintainers and users might find a changelog useful for capturing and being informed of changes in a more timely manner, ideally at the same time as getting the changes.

Test results

README: my pull request adding a README to the project root was accepted within a month of my commit.

Changelog: my changelog PR was accepted within a day. Minutes later, Trongate's AI assistant, Grady, updated the changelog with the latest changes.

That seems like early, concrete evidence that a changelog is a more practical documentation artifact to keep up to date.

Next steps

Open questions:

Will the changelog stay up to date?
Will users find it useful?
Will it have an impact on the official docs, for example, shorten the lag between code change and doc update?

I'll observe the documentation adoption behavior over the next few months and circle back with another post once there's enough activity to draw meaningful conclusions.

Coder Legion - Recent posts tagged readme