Google AMP Cache documentation confusing and outdated

[archon810]

📖 Missing or Out-of-Date Documentation

Problem

I've started an issue on confusing and missing AMP cache documentation here: ampproject/amphtml#24326, and was asked by @morsssss to open an issue here as well. If you search for "doc" in this ticket, you'll see all the times the documentation at https://developers.google.com/amp/cache/overview and especially the section called "Google AMP Cache updates" was referenced and the related confusion.

I've been trying to get more details about how the cache works and how updating it is supposed to work in the ticket above, but so far haven't received public responses. @morsssss is helping by nudging the relevant parties.

TIA.

Location

https://developers.google.com/amp/cache/overview

[morsssss]

Thanks, @archon810 !

At least in the past, documentation in various places tended to oversell what the update-cache API could really do. My guidance to site owners has generally been to rely on <amp-list> for content that needs to be absolutely fresh.

We should get the latest news about how the cache works, how long the API might take to update content at worst, and make a guide for that on amp.dev. We should also get the page on developers.google.com refreshed.

[archon810]

@morsssss Are you suggesting we make the article title and body itself an <amp-list>? I don't think @westonruter would like this idea 😶. These two are the ones we are worried about the most and where we fix typos and add updates.

[morsssss]

Nope! You shouldn't.

I'm just saying that I've seen other cases in which people weren't able to get the cache to refresh as quickly as they needed it to. So I've learned to avoid telling people they can rely on it.

[archon810]

Let's change that, together!

[tannerbaum]

Overall a documentation overhaul would be appreciated and in particular I would be surprised if this is true:

At least in the past, documentation in various places tended to oversell what the update-cache API could really do. My guidance to site owners has generally been to rely on for content that needs to be absolutely fresh.

As mentioned in a different issue we have been struggling with stale content. But even reading the the documentation for amp-live-list I wasn't sure if it would help because my understanding was it updates the client if it detects an update on the cached article, but that wouldn't matter if the cached article is stale. But maybe I misunderstood and live-list is the solution.

Even so, I am surprised by how stale the articles get and how they don't seem to respect the max-age header 😮

[morsssss]

@CrystalOnScript , just thought I should bring this to your attention...

[CrystalOnScript]

Hi @morsssss, I've spent significant time looking into these issues and I do not understand why it is being brought to my attention. We do not document Google's AMP cache on amp.dev. I suggest filing a bug on documentation at developers.google.com. If you are unsure how to do this Lizzi may be able to help.

[CrystalOnScript]

Update: I've started a project tracker for examples, documentation, and advice we can give developers from the AMP Framework side to avoid possible issues with AMP caches. I'll give updates here when I have any! In the meantime, I would love to hear any solutions currently in use or any resources I may be unaware of.

[archon810]

Here are the 4 questions/concerns I still can't get a definitive answer to after many months, with the documentation being confusing, ambiguous, or misleading:

1. Why is update-cache needed at all, given s-maxage, max-age, and the promise on this page https://developers.google.com/amp/cache/overview to invalidate and refresh the cache automatically after max-age?
2. max-age is not being respected when max-age is relatively short? Is it being respected at all? How's it supposed to work?
3. What’s the deal with s-maxage vs max-age? We were at one point told to use s-maxage but it's max-age that is all over the docs.
4. The update-cache API doesn’t update quickly enough.

https://webmasters.googleblog.com/2020/02/best-practices-for-news-coverage-with.html posted in February was still pushing update-cache. I don't understand why we need to worry about it at all and why we can't just set, say, a 15-min lifetime on each post and then once the cache is older, Google CDN would just refetch automatically?

[morsssss]

@archon810 , I believe you and I have been through all your questions over private chat. Answers:

1. If you use max-age, you don't have to use the update-cache API.
2. max-age is the way to tell Google's AMP cache when to seek a new copy. It is respected.
3. Don't use s-maxage.
4. All of us would love it if the update-cache API worked very quickly, but given the size and scale of the infrastructure, that's a difficult problem to solve.

I hadn't seen that blog post you reference. I agree that this should be updated!

I know you had a specific issue earlier! I tried to get you to reproduce it for me a few months ago, but you became unresponsive. If you've got one now, please file it in a new issue. I'd very much like to see any problem pursued to resolution!