1 files changed, 177 insertions, 0 deletions
diff --git a/docs/docs/duration.md b/docs/docs/duration.md
new file mode 100644
index 0000000..0801d9e
--- /dev/null
+++ b/docs/docs/duration.md
@@ -0,0 +1,177 @@
+# Duration
+
+The `Duration` class is inherited from the native `timedelta` class.
+It has many improvements over the base class.
+
+!!!note
+
+    Even though, it inherits from the `timedelta` class, its behavior is slightly different.
+    The more important to notice is that the native normalization does not happen, this is so that
+    it feels more intuitive.
+
+    ```python
+    >>> import pendulum
+    >>> from datetime import datetime
+
+    >>> d1 = datetime(2012, 1, 1, 1, 2, 3, tzinfo=pytz.UTC)
+    >>> d2 = datetime(2011, 12, 31, 22, 2, 3, tzinfo=pytz.UTC)
+    >>> delta = d2 - d1
+    >>> delta.days
+    -1
+    >>> delta.seconds
+    75600
+
+    >>> d1 = pendulum.datetime(2012, 1, 1, 1, 2, 3)
+    >>> d2 = pendulum.datetime(2011, 12, 31, 22, 2, 3)
+    >>> delta = d2 - d1
+    >>> delta.days
+    0
+    >>> delta.hours
+    -3
+    ```
+
+## Instantiation
+
+To create a `Duration` instance, you can use the `duration()` helper:
+
+```python
+>>> import pendulum
+
+>>> it = pendulum.duration(days=1177, seconds=7284, microseconds=1234)
+```
+
+!!!note
+
+    Unlike the native `timedelta` class, durations support specifying
+    years and months.
+
+    ```python
+    >>> import pendulum
+
+    >>> it = pendulum.duration(years=2, months=3)
+    ```
+
+    However, to maintain compatibility, native methods and properties will
+    make approximations:
+
+    ```python
+    >>> it.days
+    820
+
+    >>> it.total_seconds()
+    70848000.0
+    ```
+
+## Properties and Duration Methods
+
+The `Duration` class brings more properties than the default `days`, `seconds` and
+`microseconds`.
+
+```python
+>>> import pendulum
+
+>>> it = pendulum.duration(
+...     years=2, months=3,
+...     days=1177, seconds=7284, microseconds=1234
+... )
+
+>>> it.years
+2
+>>> it.months
+3
+
+# Weeks are based on the total of days
+# It does not take into account years and months
+>>> it.weeks
+168
+
+# Days, just like in timedelta, represents the total of days
+# in the duration. If years and/or months are specified
+# it will use an approximation
+>>> it.days
+1997
+
+# If you want the remaining days not included in full weeks
+>>> it.remaining_days
+1
+
+>>> # The remaining number in each unit
+>>> it.hours
+2
+>>> it.minutes
+1
+
+# Seconds are, like days, a special case and the default
+# property will return the whole value of remaining
+# seconds just like the timedelta class for compatibility
+>>> it.seconds
+7284
+
+# If you want the number of seconds not included
+# in hours and minutes
+>>> it.remaining_seconds
+24
+
+>>> it.microseconds
+1234
+```
+
+If you want to get the duration in each supported unit
+you can use the appropriate methods.
+
+```python
+# Each method returns a float like the native
+# total_seconds() method
+>>> it.total_weeks()
+168.15490079569113
+
+>>> it.total_days()
+1177.0843055698379
+
+>>> it.total_hours()
+28250.02333367611
+
+>>> it.total_minutes()
+1695001.4000205665
+
+>>> it.total_seconds()
+101700084.001234
+```
+
+Similarly, the `in_xxx()` methods return the total duration in each
+supported unit as a truncated integer.
+
+```python
+>>> it.in_weeks()
+168
+
+>>> it.in_days()
+1997
+
+>>> it.in_hours()
+28250
+
+>>> it.in_minutes()
+1695001
+
+>>> it.in_seconds()
+101700084
+```
+
+It also has a handy `in_words()` method, which determines the duration representation when printed.
+
+```python
+>>> import pendulum
+
+>>> pendulum.set_locale('fr')
+
+>>> it = pendulum.duration(days=1177, seconds=7284, microseconds=1234)
+>>> it.in_words()
+'168 semaines 1 jour 2 heures 1 minute 24 secondes'
+
+>>> print(it)
+'168 semaines 1 jour 2 heures 1 minute 24 secondes'
+
+>>> it.in_words(locale='de')
+'168 Wochen 1 Tag 2 Stunden 1 Minute 24 Sekunden'
+```