What about some kind of "changelog" for your documents?

[hennevogel]

          If you are already over it, I have a suggestion for you. :slightly_smiling_face:  What about some kind of "changelog" for your documents?

DocBook/GeekoDoc allows to add a so called <revhistory>. The idea is to document bigger changes, not just typos etc. For example, adding a new chapter, describing a new feature etc.

It looks like this:

<revhistory xml:id="rh-obs-guide">
   <!-- Add the latest change here -->
   <revision>
       <date>2024-07-04</date>
       <revdescription>
           <para>The description of this change</para>
       </revdescription>
   </revision>
</revhistory>

You may want to know a few things before you apply it:

• Add the latest change as the first child of <revhistory>. The reader shouldn't have to scroll down the page. They should see the first item when the rendered page opens.
• Start the xml:id of <revhistory> with rh. It's not strictly validated, but a good convention that served us well. Use different IDs for different guides.
• Use the format YYYY-MM-DD in the <date> element.
• Restrict the description to one sentence. You don't have to describe it in full detail, it should be an overview only.

Our stylesheets creates a separate HTML page. A link on the titlepage with the name Revision History: <GUIDE-TITLE> points to this separate page.

In most cases, you will probably rarely update it as there are only smaller changes. But if you do some more work, it might be useful to give the reader an idea what substantial changes to the guide were added.

By the way: don't think about (ab)using the Git log for that. 😉 We thought about that too, but a Git log is too detailed and you can't discern the bigger chunks from the smaller ones.

Originally posted by @tomschr in #354 (comment)