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.
Top comments (0)