Improve Documentation

[jdsandifer]

Based on my own experience of using the library and seeing many of the open and closed issues, it seems like it is common for people to use this library without fully understanding the intention of some of its functions.

This isn't a fault of the current documentation; when read completely and with consideration for the behavior of Dates in JS in general, it's clear what each function is intended to achieve.

However, I believe it's common to use libraries like date-fns and date-fns-tz to avoid the many tricky parts of working with dates and learning about them so I think some changes to the documentation to help educate users about Dates and how this library's functions work with them could be useful.

In addition, whether because of habit or time pressure, many devs probably aren't reading the full documentation and simply jumping to the function that they need to understand. (I know I did that the first few times.) I believe some duplication of important concepts would help each function's documentation be more complete and understandable on its own - the way it's probably most often consumed.

[jdsandifer]

@marnusw If this issue sounds reasonable, I'd be happy to open a PR with some of the ideas I had.

[toduyemi]

This would be really nice. The documentation does nothing to describe the formatting of its API. E.g. Whether parameters are in seconds or milliseconds.

[marnusw]

@jdsandifer thank you for the offer. I would welcome improvements to the documentation!