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 narrative documentation primitive and deliberately not all-inclusive so that it remains reasonably accurate and future-proof, enduring multiple future releases with zero maintenance. The changelog
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.
Top comments (0)