Update FAQ #update_faq: Link to GitHub file history

[larswmh]

While going through the FAQ for another task, I came across the #update_faq article and noticed something odd. Although we haven't merged any FAQ changes this year, it already showed a 2023 date. Instead of showing the date of the last FAQ change, it shows the date from when the site was built. Every merged PR or scheduled deployment would update that date, not just FAQ changes like intended.

After thinking about fixing this, I came up with an alternative idea. In my opinion, it doesn't really make sense to specify this in the FAQ if it's always up to date anyway. Especially not if that is the only information included in the FAQ article, with no text whatsoever. Linking to the GitHub file history for faq_de.json / faq.json would give the visitors much more information. Not only would they see when the last change was made like before, but they would now see what has changed in specific. They can see any change that has been made to the file in a chronological order.

(After taking the comments below into consideration, a date within the FAQ article itself has been re-added)

With the changes I've made in this PR, the article would look like this:

I am looking forward to your feedback.

---

Internal Tracking ID: EXPOSUREAPP-14522

[Ein-Tim]

I would vote for still including a date in the entry, as not tech-savvy users probably won't go to GitHub revision histories. :D

[MikeMcC399]

@larswmh

I don't think that referring general readers to GitHub commit history is a good idea.

I would either leave it alone or delete the article https://www.coronawarn.app/en/faq/results/#update_faq.

If you want to keep a date, then I would put it into the footer, with text: "Website last updated on ...." (instead of FAQ last updated ...).

How long is this website going to continue to be productive? Is there an end-of-life planned?

[GisoSchroederSAP]

@larswmh

I don't think that referring general readers to GitHub commit history is a good idea.

I would either leave it alone or delete the article https://www.coronawarn.app/en/faq/results/#update_faq.

If you want to keep a date, then I would put it into the footer, with text: "Website last updated on ...." (instead of FAQ last updated ...).

How long is this website going to continue to be productive? Is there an end-of-life planned?

First of all, a happy New Year 2023 and thanks for your ongoing community support.

To give a first shot answer here: Yes, we are starting to plan the ramp-down of the the Corona-Warn-App solution and all linked systems. The whole process will be performed in stages. It is not yet finalized, what are the respective dates for each system of application, though. Most probably, we are going to add a noticable hint on the website first before it will be archived and removed at a later date. Same with the app. Hopefully, also the "official" communication will release an information about the upcoming ramp-down process, so the whole community is informed.

[GisoSchroederSAP]

Regarding the question of "last update on the footer" or the "link to change history", I'd prefer the latter way (the link) - as the date only seems to be a quite flimsy piece of information without much added value. I strongly believe, whoever clicks on the FAQ article "When were the FAQ last updated?" does not only looks for the date, but also for the underlying change context.

[MikeMcC399]

@GisoSchroederSAP

Happy New Year to you too, and to the rest of the team who I haven't mentioned individually so far!

Thanks very much for confirming that you are starting end-of-life planning. In that case any proposed change here should be considered against the remaining life-time and whether it gives significant benefit against the effort to make the change and test it.

[MikeMcC399]

I question whether most people will find the https://www.coronawarn.app/en/faq/results/#update_faq article, since it is at the bottom of the section Resolved.

[Ein-Tim]

My opinion: Best would probably be to do what @MikeMcC399 suggested and move the date into the footer.

[MikeMcC399]

Just to expand on my comment that linking to GitHub history is not very helpful for general readers: the list contains both textual and technical changes (see screenshot below).

General readers would be more interested in a curated list of text changes. This would be possible using GitHub releases which can automatically generate release notes that can be edited. This would however be a significant manual effort to implement and so I do not suggest that this be done.

[MikeMcC399]

@larswmh If you are wanting the date of the last commit to each FAQ source file, you can get this from:

$ git log -1 --pretty="format:%cs" ./src/data/faq.json 2023-01-02 $ git log -1 --pretty="format:%cs" ./src/data/faq_de.json 2023-01-02

Pretty format options are listed on https://git-scm.com/docs/pretty-formats.

This could probably be automated but it would be problematic if you want to add the last date changed into the FAQ, because that change in itself would change the last date changed.

[larswmh]

After discussing with other team members, we've internally decided to stick with the current state of the PR (screenshots in the opening comment have been adjusted). Because of aforementioned concerns that we agree with, we've re-added the date in the FAQ article. The text and link to the GitHub change history is just an extra now.

We're aware that the solution requires manual intervention every time a change is made to the FAQ, but the way it would need to be automated would create unreasonable effort at the current state of the project. We're planning to update this date only when there are real content changes, not when there are technical changes that are unobservable for the normal user.

However, thank you for the feedback @Ein-Tim @MikeMcC399. Unless there are any more critical concerns, this will be merged later today.

[Ein-Tim]

In my opinion this is worse than before, but if you want to go this way, it's ok for me. However, I suggest to make it more clear that the date refers to the whole FAQs and not only this one entry, as we have similar update notices in other FAQ entries too.

[larswmh]

@Ein-Tim

In my opinion this is worse than before, but if you want to go this way, it's ok for me. However, I suggest to make it more clear that the date refers to the whole FAQs and not only this one entry, as we have similar update notices in other FAQ entries too.

Thanks for the hint. With the divider and the text below, it is indeed similar to our update notices. I have therefore extended the text including the date to:

The last content changes to FAQ articles were made on January 4th, 2023.

---

I can understand that this is not a satisfying solution for some, but as explained earlier, we think this is the best way to go right now. The amount of FAQs being modified content-wise is manageable and if there are a lot of changes, they mostly happen all at once, for example for a new release.

[dsarkar]

@Ein-Tim @MikeMcC399 Many thanks for reviewing and providing your assessments. We will merge for now the current PR, however, as usual, we are open to suggestions and changes.

[MikeMcC399]

@larswmh

This PR fails the Cypress test faq_link_attr.

According to the convention described in Links on FAQ pages:

"All internal and external links on the FAQ pages should use the HTML hyperlink attribute target='_blank' to open in a new frame. This provides a consistent user experience and works around an issue with the browser back arrow button in the FAQ Glossary."

The link <a href='#glossary_github'>GitHub</a> does not conform to this requirement.

Perhaps we should consider running these tests automatically for pull requests so that there is no surprise later?

[larswmh]

@MikeMcC399

Thanks for the information. A new PR has been submitted to fix this

Perhaps we should consider running these tests automatically for pull requests so that there is no surprise later?

I have brought this up internally once again. Since we have similar checks running in the app repositories, I don't think it's too unrealistic we can add automated Cypress tests here too.

[MikeMcC399]

@larswmh

I have brought this up internally once again. Since we have similar checks running in the app repositories, I don't think it's too unrealistic we can add automated Cypress tests here too.

I can prepare something for this if you like. Please let me know.