Documentation enhancements

[ddeboer]

Some ideas for improving the docs in preparation for 2.0.

• 1. Add FAQ, e.g.
  1. ‘Q. Why is nothing purged? A. Check that you are calling flush()’.
  2. ‘Q. Which invalidation methods are supported? A. Check table.’
  3. Checking Varnish logs while testing (varnishlog -N /tmp/foshttpcache-varnish/_.vsm).
  4. Varnish how to: Login redirect infinite loop FOSHttpCacheBundle#227 (comment)
• 2. Rename ‘Caching Proxy Configuration’ to ‘Proxy Server Configuration’ (or Caching Server Configuration). This creates a clearer contrast with the next chapter, ‘Caching Proxy Clients’ (and perhaps rename that to ‘Proxy Clients’).
• 3. ‘Caching Proxy Clients’: emphasise that only 1 client needs to be created.
• 4. Move the introductory chapter on cache invalidation to the end of the docs?
• 5. Remove version constraint from $ composer install (and let Composer find the right one).
• 6. Add a glossary: caching proxy (server), ….

[dbu]

+1 for the renaming. yeah lets just talk about a proxy and a proxy client. i think we can do most of that even for version 1.

only point i am not entirely sure is moving 4 to the end. i think the introduction does help people not familiar with it. and we have the install and config and overview chapter before that for the impatient. but i am not strictly against it, lets discuss in amsterdam ;-)

[ddeboer]

• Move HTTP adapter customization to a separate file
• Move Using the Clients to a separate file
• Add a list with anchors for Varnish/Nginx/Symfony clients (emphasise only one is needed)
• Keep Proxy Clients chapter short and to the point

[purplefish32]

How about : "How to purge/ban chache for a single user"

[dbu]

@purplefish32 is that an entry for the FAQ? what exactly do you mean with "for a single user"?

[purplefish32]

Yes I ment that as a FAQ entry, sorry that was not specific enough.
Purging/Baning a spécific users cached version of a page is hard to understand.

Example : A user is promoted to admin in a platform, he get lots of new shiny buttons in the menu. I am guessing you have to bust all the pages using a Vary on the PHPSESSID cookie. I dont know if this is the correct way to handle the problem or not, or if this is typicly the case for ESI.

[dbu]

@purplefish32 if you use the user context, you would want to invalidate the hash lookup request for that user. i don't think that this would be possible with the current ban setup - you would have to ban all lookups which should usually not hurt much, assuming there are not that many promotions. but indeed this could either be discussed in the doc chapter about user context or in the faq.
@lolautruche how do you handle this situation in ez publish?

[lolautruche]

@dbu User context hash is cached as well using Http cache, with a 10 minuntes expiration. We chose to wait for these 10 minutes.

[dbu]

i looked over the doc again and propose we close this issue. the important bits are done. 4/6 is both in that introduction and i like to have that in the beginning so people reading the whole thing see it. people looking for specific information will have deep links from google likely anyways, or look over the toc to find the information they look for.

as for a FAQ, it would be a grouping together of information that is also present elsewhere. to keep documentation efforts manageable, i'd prefer to not do that at this time. if we notice the same questoins coming over and over again, i am not opposed to have a FAQ.

@ddeboer is that ok with you?

[dbu]

i looked over the doc again and propose we close this issue. the important bits are done. 4/6 is both in that introduction and i like to have that in the beginning so people reading the whole thing see it. people looking for specific information will have deep links from google likely anyways, or look over the toc to find the information they look for.

as for a FAQ, it would be a grouping together of information that is also present elsewhere. to keep documentation efforts manageable, i'd prefer to not do that at this time. if we notice the same questoins coming over and over again, i am not opposed to have a FAQ.

@ddeboer is that ok with you?