Refining how updates to documentation articles are tracked (improving the changelog)

[ndiego]

The public-facing changelog on Documentation articles provides end-users and Docs contributors with a record of what changed in the article. This can be especially useful when there are functionality changes.

That said, the current implementation is not ideal, and the design is cumbersome, especially on articles with many updates. Here is some additional feedback on this in Figma. More often than not, the changelog includes editorial changes to the page that are not relevant to users reading the documentation.

Example 1	Example 2

Here are a couple of ideas on how to solve this.

Using a Details/Summary block

In this case, the Changelog section would still appear on the front end, but the content would be contained within a Details/Summary block. We would need to add some custom styles to this, but the information would still be visible on the front end; it would just be hidden unless the end user wants to review the changes.

Creating a custom Changelog block

An alternative would be to create a custom "Changelog", or "Contributor Notes" block that would be visible in the Editor, but not on the front end. This would allow contributors to note changes made to the article and anything else that is needed for content management without the end users seeing it.

I am personally a fan of a custom block that is not visible to end-users. I am not convinced that the average user needs to know the full history of an article, but this is important to Docs contributors working on the content. This functionality is one of the main reasons I built the Block Visibility plugin 😅

[ryelle]

If having something only visible in the admin is acceptable, do you think the Internal Notes plugin would work? It can track when content changes, and users can manually add notes. It's in use the Pattern Directory, here's an example:

I think it would still need some configuration (and fixing that icon alignment), but it would be less effort than a custom block.

Another benefit to internal notes is that if it is decided that we should show this on the frontend in some special style, it would already be distinct from the main article content.

[ndiego]

If having something only visible in the admin is acceptable, do you think the Internal Notes plugin would work? It can track when content changes, and users can manually add notes. It's in use the Pattern Directory,

That's pretty cool, and it looks like it could work nicely. I didn't know the Internal Notes plugin existed. What do you think @estelaris?

[zzap]

@nickdaugherty I would really, really love to have changelog visible to everyone. Potentially, it would be good to move it on a second page (after <!--nextpage-->) if that still exists.

[ndiego]

I would really, really love to have changelog visible to everyone. Potentially, it would be good to move it on a second page (after ) if that still exists.

In concept, I think having the Changelogs available for folks to see would be very beneficial. In practice, though, the majority of the existing Changelogs are poorly formatted, often contain spelling errors, and are not descriptive enough to help you understand what changed or why it's important that it changed, like "screenshot of toolbar" and "added video". But that's more of a content management issue.

What if you put the Changelog in a stylized Summary/Details block? Then the content is available but closed by default and does not take up so much space on the page.

[zzap]

What if you put the Changelog in a stylized Summary/Details block? Then the content is available but closed by default and does not take up so much space on the page.

That could work too, yes.