diff --git a/CHANGELOG.md b/CHANGELOG.md
index 4dd9788e2d5759f1eaea9fdb3044543829f31f69..30c3ed9a0f62ec84180eccc592cc573cd21fab6f 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -13,6 +13,7 @@
   * helper methods defined on `ApplicationController` are available in popover by default, and a configuration option is added to disable this behavior
   * all application helpers are included by default, and a configuration option is added to disable this behavior
   * empty popover params are not frozen anymore
+- docs: update and improve docs
 
 ### v1.0.3
 - fix commit f989786 that changed the wrong line (0b7832e)
diff --git a/docs/case-studies/use-stimulus-and-turbo.md b/docs/case-studies/use-stimulus-and-turbo.md
index 06ab6afcc7be229b8c2b35cb6078027d0db28479..77e39cd11eb97f7538f07ff620aedaea0a656a5b 100644
--- a/docs/case-studies/use-stimulus-and-turbo.md
+++ b/docs/case-studies/use-stimulus-and-turbo.md
@@ -8,7 +8,7 @@ nav_order: 4
 # {{ page.title }}
 
 If you are using both [Stimulus](https://stimulus.hotwired.dev/) and [Turbo](https://turbo.hotwired.dev/) from [Hotwired](https://hotwired.dev/),
-here's a Stimulus controller I recommend setting up on your popover layouts to improve your developer experience and easily controller the popovers.
+here's a Stimulus controller you can set up on your popover layouts to improve your developer experience and easily controller the popovers.
 
 This uses the [Stimulus dispatch API](https://stimulus.hotwired.dev/reference/controllers#cross-controller-coordination-with-events) and [Turbo events](https://turbo.hotwired.dev/reference/events).
 
diff --git a/docs/guides/control-popover.md b/docs/guides/control-popover.md
index 498ec193ab5ec394c1df814be1e8aee132192d68..f40c5a17e9f6c1e0986d6107abfdf694b81af9d4 100644
--- a/docs/guides/control-popover.md
+++ b/docs/guides/control-popover.md
@@ -32,6 +32,12 @@ coupdoeilElement.openPopover()
 coupdoeilElement.closePopover()
 ```
 
+### Check state
+
+```js
+coupdoeilElement.dataset.popoverOpen // 'true' if popover is open, else undefined 
+```
+
 ### disabling/enabling
 
 A `coup-doeil` element can be disabled so the popover won't open, regardless of the trigger option selected.
@@ -69,4 +75,4 @@ popover.coupdoeilElement
 ## Using Stimulus and Turbo
 
 If you are using both [Stimulus](https://stimulus.hotwired.dev/) and [Turbo](https://turbo.hotwired.dev/) from [Hotwired](https://hotwired.dev/), 
-I recommend setting up a Stimulus controller on your popover layouts as depicted in [this example](/case-studies/using-stimulus-and-turbo.html).
+you can set up a Stimulus controller on your popover layouts as depicted in [this example](/case-studies/using-stimulus-and-turbo.html).
diff --git a/docs/html-elements.md b/docs/html-elements.md
index a25be298091b241067ec0bc53137a6e452bb966a..aaddeb1b67c154436a69895fbd10a69c302be9e9 100644
--- a/docs/html-elements.md
+++ b/docs/html-elements.md
@@ -55,4 +55,4 @@ and an inline style attribute to actually position it.
 
 ### Controlling the popover
 
-If you need to control the popover, check the [Control or disable popover page]().
+If you need to control the popover, check the [Control or disable popover page](/guides/control-popover.html).