docs: 📝 Update documentation structure and layout

README.md

@@ -8,29 +8,29 @@
 
 ## What's this?!
 
-This is a very little package with **React hooks wrapping time-related Vanilla JS functions**, 
+This is a very little package with **React hooks wrapping time-related vanilla Javascript functions**,
 so you can use them with minimal effort in your React apps without having to worry about manual 
 clean up, or writing boilerplate to pause/resume intervals etc.
 
 ### Feature Overview
 
-* Several React hooks **wrapping Vanilla JS functions** like:
-  * setInterval() – [All Hooks][interval-api] | [MDN][interval-mdn]
-  * setTimeout() – [All Hooks][timeout-api] | [MDN][timeout-mdn]
-  * window.requestAnimationFrame() – [All Hooks][raf-api] | [MDN][raf-mdn]
-  * window.requestIdleCallback() – [All Hooks][idle-cb-api] | [MDN][idle-cb-mdn]
-* …and **additional [utility hooks][all-hooks]** for things like
-  * rate-limiting: `useThrottledState()`, `useDebounce()`, `useThrottle()`
-  * rendering: `useAnimationFrameLoop()`
-  * counters: `useCounter()`, `useCountdown()`, `useTimer()`
+* Hooks for all timing-related **vanilla JS functions** like:
+  * setInterval() –> [useInterval()][interval-api] | [MDN][interval-mdn]
+  * setTimeout() –> [useTimeout()][timeout-api] | [MDN][timeout-mdn]
+  * requestAnimationFrame() –> [useAnimationFrame()][raf-api] | [MDN][raf-mdn]
+  * requestIdleCallback() –> [useIdleCallback()][idle-cb-api] | [MDN][idle-cb-mdn]
+* …and **additional [utility hooks][all-hooks]** for common tasks like
+  * throttling: `useThrottledState()`, `useThrottle()`, `useDebounce()`
+  * GFX/animation/rendering: `useAnimationFrameLoop()`
+  * reactive counters: `useCounter()`, `useCountdown()`, `useTimer()`
   * time: `useClock()`
-  * effects: `useTimeoutEffect()`, `useIdleCallbackEffect()`
-* Ability to **pause, resume, start or stop intervals**
+  * async effects: `useTimeoutEffect()`, `useIdleCallbackEffect()`
+* **Reactive intervals**: intervals can be controlled via **pause, resume, start or stop**
 * A **versatile API**: customizable settings, many hook "flavors" depending on the use-case.
-* **Automatic clean-ups** of pending timers, intervals etc.
+* **Automatic clean-ups** of pending timers, intervals etc. on unmount
 * Callbacks are **automatically memoized**
 * Full **Typescript** support
-* **[Lightweight](https://bundlephobia.com/result?p=react-timing-hooks)** (less than 2KB minzipped, no transitive dependencies!)
+* Very **[lightweight](https://bundlephobia.com/result?p=react-timing-hooks)** (no transitive dependencies!)
 * **Tree-shakable** — You only bundle what you use!
 
 
@@ -52,7 +52,7 @@ yarn add react-timing-hooks
 
 https://ericlambrecht.github.io/react-timing-hooks/migrations/
 
-## Examples
+## Some Examples
 
 #### A "status logger" with `useInterval()`
 ```jsx harmony

docs/callbacks/index.md

@@ -0,0 +1,20 @@
+---
+layout: default
+title: Callbacks / Functions
+nav_order: 3
+has_children: true
+---
+
+# Timeouts
+
+React hooks that return some form of timed callback.
+{: .fs-6 .fw-300 }
+
+Most of these callbacks are based on [setTimeout()][timeout-mdn].
+
+For *rate-limiting* use `useThrottle()` or `useDebounce()`. For *pure timeouts* use `useTimeout()` or `useTimeoutEffect()`.
+
+{: .note }
+All of these hooks are memoized and will automatically take care of clearing any pending timeouts on unmount.
+
+[timeout-mdn]: https://developer.mozilla.org/en-US/docs/Web/API/setTimeout

docs/animation-api/useAnimationFrame.md → docs/callbacks/useAnimationFrame.md

@@ -1,15 +1,17 @@
 ---
 title: useAnimationFrame
-parent: Animation
+parent: Callbacks / Functions
 nav_order: 2
 ---
 
 # useAnimationFrame
 
 Use this hook to create a callback that executes the provided function via [`window.requestAnimationFrame()`][raf-mdn].
 
-_This hook is quite low level._ 
-You might want to use `useAnimationFrameLoop()` or `useIdleCallback()` instead.
+{: .highlight-title }
+> Note
+>
+> _This hook is quite low level._ You might want to use `useAnimationFrameLoop()` or `useIdleCallback()` instead.
 
 ## Example
 

docs/timeouts-api/useDebounce.md → docs/callbacks/useDebounce.md

@@ -1,6 +1,6 @@
 ---
 title: useDebounce
-parent: Timeouts
+parent: Callbacks / Functions
 nav_order: 4
 ---
 
@@ -12,8 +12,11 @@ Debounces a callback.
 Use this hook if you want a function that "blocks" consecutive calls until a specified
 time has passed since the last invocation. This is called **debouncing**.
 
-If you want a callback that [doesn't debounce but throttles][thr-vs-deb], take a look at `useThrottle()`.
-
+{: .note-title }
+> Throttle vs. Debounce
+>
+> If you want a callback that [doesn't debounce but throttles][thr-vs-deb], take a look at `useThrottle()`.
+
 If you want a non-debouncing and non-throttling version, take a look at `useTimeout()`.
 
 Pending timeouts will also be cleared in case the component unmounts.

docs/idle-callback-api/useIdleCallback.md → docs/callbacks/useIdleCallback.md

@@ -6,10 +6,11 @@ nav_order: 1
 
 # useIdleCallback
 
-Use this hook if you want to delay the execution of a function to a time when the browser is idle.
+Use this hook if you want to delay the execution of a function to a time **when the browser is idle**.
 
 A good use-case for this might be _user tracking_, for instance.
 
+{: .important }
 See [requestIdleCallback()](https://developer.mozilla.org/en-US/docs/Web/API/Window/requestIdleCallback) to learn
 more about the concept of "idle callbacks".
 

docs/timeouts-api/useThrottle.md → docs/callbacks/useThrottle.md

@@ -1,6 +1,6 @@
 ---
 title: useThrottle
-parent: Timeouts
+parent: Callbacks / Functions
 nav_order: 3
 ---
 
@@ -12,8 +12,11 @@ Throttles a callback.
 Can be used for **rate-limiting** – the callback will only be invoked every X milliseconds (X being the set timeout),
 even if it was called more frequently.
 
-Similar, [but different(!)][thr-vs-deb], is the `useDebounce()` hook, which blocks the invocation entirely until the function was
-stopped being called for X milliseconds.
+{: .note-title }
+> Throttle vs. Debounce
+>
+> Similar, [but different(!)][thr-vs-deb], is the `useDebounce()` hook, which blocks the invocation entirely until the function was
+> stopped being called for X milliseconds.
 
 By default, the throttled function will always be called immediately (`options.leading` is true by default) and then
 (`options.trailing` is true by default) also after every X milliseconds for consecutive calls.

docs/timeouts-api/useTimeout.md → docs/callbacks/useTimeout.md

@@ -1,6 +1,6 @@
 ---
 title: useTimeout
-parent: Timeouts
+parent: Callbacks / Functions
 nav_order: 2
 ---
 
@@ -17,6 +17,8 @@ If you want a throttling version, see `useThrottle()`.
 
 Pending timeouts will only(!) be cleared in case the component unmounts.
 
+#### Alternatives
+
 If you want to execute a timeout every time a certain value changes, `useTimeoutEffect` might be better suited.
 
 ## Example

docs/idle-callback-api/index.md → docs/effects/index.md

@@ -1,11 +1,11 @@
 ---
 layout: default
-title: Idle Callbacks
-nav_order: 5
+title: Effects
+nav_order: 4
 has_children: true
 ---
 
-# Idle Callbacks
+# Effects
 
 React hooks that wrap [window.requestIdleCallback()][idle-cb-mdn].
 {: .fs-6 .fw-300 }

docs/idle-callback-api/useIdleCallbackEffect.md → docs/effects/useIdleCallbackEffect.md

@@ -1,6 +1,6 @@
 ---
 title: useIdleCallbackEffect
-parent: Idle Callbacks
+parent: Effects
 nav_order: 2
 ---
 

docs/timeouts-api/useTimeoutEffect.md → docs/effects/useTimeoutEffect.md

@@ -1,6 +1,6 @@
 ---
 title: useTimeoutEffect
-parent: Timeouts
+parent: Effects
 nav_order: 1
 ---
 

docs/index.md

@@ -19,37 +19,48 @@ npm i react-timing-hooks
 yarn add react-timing-hooks
 ```
 
-**Note:** You have to install React `^16.8.0`, `^17.0.0` or `^18.0.0`, too, in order to use this package.
+{: .note }
+Since this is a React package, you have to install React `^16.8.0`, `^17.0.0` or `^18.0.0`, too, in order to use this package.
+
+## Getting started
+
+Simply import the hook you need and use it in your React app! Here is an overview of all hooks in this package: [list of all hooks](/react-timing-hooks/list-of-all-hooks/).
+
+{: .important-title }
+> Typescript
+>
+> This package is developed in Typescript, so **everything is typed out of the box**. You don't need to install types seperately.
    
-## Overview
+## Background
 
 In general all of these hooks are more or less wrappers for standard javascript functions. But since they can be quite
 a pain to handle in React components (leaks upon unmount etc.), I wrote this little package.
 
 There are currently hooks available for:
 
-* setTimeout (useTimeout, useTimeoutEffect)
-* setInterval (useInterval, useTimer, useClock)
-* requestAnimationFrame (useAnimationFrame, useAnimationFrameLoop)
-* requestIdleCallback (useIdleCallback, useIdleCallbackEffect)
+* [setTimeout][timeout-mdn] (useTimeout, useTimeoutEffect, useThrottledState, ...)
+* [setInterval][interval-mdn] (useInterval, useTimer, useClock, ...)
+* [requestAnimationFrame][raf-mdn] (useAnimationFrame, useAnimationFrameLoop)
+* [requestIdleCallback][idle-cb-mdn] (useIdleCallback, useIdleCallbackEffect)
 
-The APIs of all hooks are documented on this page (see sidebar). They should be pretty straight forward, but feel free
+**All hooks are documented on this page** (see sidebar). They should be pretty straight forward to use, but feel free
 to add an issue on GitHub if you have any ideas for improvement.
 
-### Typescript
+{: .note-title }
+> Package size / Treeshaking
+> 
+> This package is extremely small already (see [here](https://bundlephobia.com/result?p=react-timing-hooks)), but your bundle
+> size will be even less affected by this package, because it's completely **tree-shakable**, i.e. only hooks you actually use
+> will be bundled into your app js.
 
-This package is developed in Typescript, so everything is typed out of the box. You don't need to install types seperately.
-
-### Package size / Treeshaking
+### Preventing leaks on unmount
 
-This package is extremely small already (see [here](https://bundlephobia.com/result?p=react-timing-hooks)), but your bundle
-size will be even less affected by this package, because it's completely **tree-shakable**, i.e. only hooks you actually use
-will be bundled into your app js.
+One of the most cumbersome things when dealing with timeouts and intervals in React is the **boilerplate** you have to write in order to use them properly.
 
-### Preventing leaks on unmount
+What you what normally do is to write clean-up code to manually clear pending timeouts/intervals in your React components. 
+**With React Timing Hooks you don't have to do that.**
 
-Normally, timeouts, intervals etc. would have to be cleaned up manually if used inside a React component. 
-With React Timing Hooks you don't have to do that.
+#### Example
 
 For example: You might have a timeout that runs under a certain condition. In this case a cleanup
 has to be done in a separate `useEffect` call that cleans everything up (but only on unmount).
@@ -108,7 +119,7 @@ In this case `react-timing-hooks` automatically took care of cleaning up the tim
 
 ### Memoization
 
-You **don't have to worry about memoization** of your callbacks (by using `useCallback`) for example. React Timing Hooks is taking care of that for you. So even if you pass a simple inline arrow function to one of these hooks, the return value (if there is one) will not change on every render but instead stay the same (i.e. it will be memoized).
+Memoization is important if you depend on callbacks in your hook dependency arrays. You **don't have to worry about memoization** of your callbacks (by wrapping stuff in `useCallback` for example). React Timing Hooks is taking care of that for you. So even if you pass a simple inline arrow function to one of these hooks, the return value (if there is one) will not change on every render but instead stay the same (i.e. it will be memoized).
 
 This means something like this is safe to do:
 
@@ -122,3 +133,7 @@ useEffect(() => {
 }, [foo, onFooChange])
 ```
 
+[interval-mdn]: https://developer.mozilla.org/en-US/docs/Web/API/setInterval
+[timeout-mdn]: https://developer.mozilla.org/en-US/docs/Web/API/setTimeout
+[idle-cb-mdn]: https://developer.mozilla.org/en-US/docs/Web/API/Window/requestIdleCallback
+[raf-mdn]: https://developer.mozilla.org/en-US/docs/Web/API/window/requestAnimationFrame

docs/list-of-all-hooks/index.md

@@ -1,41 +1,55 @@
 ---
 layout: default
 title: List of all hooks
-nav_order: 7
+nav_order: 6
 has_children: false
 ---
 
-# List of all hooks
+# A list of all hooks
 
 In case you wonder where to find them.
 {: .fs-6 .fw-300 }
 
-## Base Vanilla JS wrappers
+## By Javascript function
+
+#### Set Timeout | [MDN][timeout-mdn]
 - [useTimeout](/react-timing-hooks/timeouts-api/useTimeout.html)
 - [useTimeoutEffect](/react-timing-hooks/timeouts-api/useTimeoutEffect.html)
+
+#### Set Interval | [MDN][interval-mdn]
 - [useInterval](/react-timing-hooks/intervals-api/useInterval.html)
-- [useIdleCallback](/react-timing-hooks/idle-callback-api/useIdleCallback.html)
+
+#### Request Idle Callback | [MDN][idle-cb-mdn]
+- [useIdleCallback](/react-timing-hooks/idle-callback-api/useIdleCallback.html).
 - [useIdleCallbackEffect](/react-timing-hooks/idle-callback-api/useIdleCallbackEffect.html)
+
+#### Request Animation Frame | [MDN][raf-mdn]
 - [useAnimationFrame](/react-timing-hooks/animation-api/useAnimationFrame.html)
 - [useAnimationFrameLoop](/react-timing-hooks/animation-api/useAnimationFrameLoop.html)
 
-## By Use Case
+## By use case
 
-### Rate Limiting, Throttling, Debouncing
+#### Rate limiting / throttling / debouncing
 - [useThrottledState](/react-timing-hooks/general-utility/useThrottledState.html) - tame rapid firing state updates, reducing the number of React updates
 - [useThrottle](/react-timing-hooks/timeouts-api/useThrottle.html)
 - [useDebounce](/react-timing-hooks/timeouts-api/useDebounce.html)
 
-### Counting
+#### Reactive counters & timers
 - [useCounter](/react-timing-hooks/intervals-api/useCounter.html) - a reactive, customizable counter
 - [useTimer](/react-timing-hooks/intervals-api/useTimer.html) - a timer
 - [useCountdown](/react-timing-hooks/intervals-api/useCountdown.html) - a countdown (ends automatically)
 
-### Rendering
+#### GFX / animation /  rendering
 - [useAnimationFrameLoop](/react-timing-hooks/animation-api/useAnimationFrameLoop.html) - for animations, rendering etc.
 
-### Time
+#### Time
 - [useClock](/react-timing-hooks/intervals-api/useClock.html) - displays a real-time digital clock
 
-### Tracking
+#### Tracking
 - [useIdleCallback](/react-timing-hooks/idle-callback-api/useIdleCallback.html)**
+
+
+[interval-mdn]: https://developer.mozilla.org/en-US/docs/Web/API/setInterval
+[timeout-mdn]: https://developer.mozilla.org/en-US/docs/Web/API/setTimeout
+[idle-cb-mdn]: https://developer.mozilla.org/en-US/docs/Web/API/Window/requestIdleCallback
+[raf-mdn]: https://developer.mozilla.org/en-US/docs/Web/API/window/requestAnimationFrame