diff --git a/doc/man1/timew-config.1.adoc b/doc/man1/timew-config.1.adoc
index ef6556d7..b5bc0efa 100644
--- a/doc/man1/timew-config.1.adoc
+++ b/doc/man1/timew-config.1.adoc
@@ -8,7 +8,7 @@ timew-config - get and set Timewarrior configuration
 *timew config* [_<name>_ {_<value>_|*''*}]
 
 == DESCRIPTION
-Allows setting and removing configuration values, as an alternative to directly editing your ~/.timewarrior/timewarrior.cfg file.
+Allows setting and removing configuration values, as an alternative to directly editing your _timewarrior.cfg_ file.
 
 == EXAMPLES
 For example:
@@ -34,4 +34,4 @@ If no arguments are provided, all configuration settings are shown:
 
 == SEE ALSO
 **timew-hints**(1),
-**timew-show**(1)
\ No newline at end of file
+**timew-show**(1)
diff --git a/doc/man1/timew.1.adoc b/doc/man1/timew.1.adoc
index b756eb34..907d0c61 100644
--- a/doc/man1/timew.1.adoc
+++ b/doc/man1/timew.1.adoc
@@ -132,12 +132,20 @@ Note that the online documentation can be more detailed and more current than th
 
 == FILES
 
+=== Non-Unix systems
 ~/.timewarrior/timewarrior.cfg::
     User configuration file.
 
 ~/.timewarrior/data/YYYY-MM.data::
     Time tracking data files.
 
+=== Unix systems
+${XDG_CONFIG_HOME:-$HOME/.config}/timewarrior/timewarrior.cfg::
+    User configuration file if legacy _~/.timewarrior_ directory doesn't exist.
+
+${XDG_DATA_HOME:-$HOME/.local/share}/timewarrior/data/YYYY-MM.data::
+    Time tracking data files if legacy _~/.timewarrior_ directory doesn't exist.
+
 == pass:[CREDITS & COPYRIGHT]
 Copyright (C) 2015 - 2018 T. Lauf, P. Beckingham, F. Hernandez. +
 Timewarrior is distributed under the MIT license.
diff --git a/doc/man7/timew-config.7.adoc b/doc/man7/timew-config.7.adoc
index d3ceedff..9b8ecb9a 100644
--- a/doc/man7/timew-config.7.adoc
+++ b/doc/man7/timew-config.7.adoc
@@ -7,7 +7,29 @@ timew-config - Timewarrior configuration file and override options
 **timew rc.**__<name>__**=**__<value>__ _<command>_
 
 == DESCRIPTION
-Timewarrior stores its configuration in the user's home directory in _~/.timewarrior/timewarrior.cfg_.
+Timewarrior stores its configuration in the user's home directory in _~/.timewarrior/timewarrior.cfg_ on non-Unix systems (e.g. Windows or macOS).
+On Unix systems, XDG Base Directory specification is supported, if _~/.timewarrior_ directory doesn't exist
+(old config directory is still supported and has precedence over XDG BD compliant locations).
+This means configuration is stored in
+_$XDG_CONFIG_HOME/timewarrior/timewarrior.cfg_, which defaults to
+_~/.config/timewarrior/timewarrior.cfg_ if _$XDG_CONFIG_HOME_ environment
+variable is not specified.
+
+Those wanting to migrate their data to a new directory scheme, might do that with following shell snippet:
+
+[source,shell]
+----
+LEGACY="${HOME}/.timewarrior"
+CONFIG_DIR="${XDG_CONFIG_HOME:-$HOME/.config}/timewarrior"
+DATA_DIR="${XDG_DATA_HOME:-$HOME/.local/share}/timewarrior"
+mkdir -p "${CONFIG_DIR}"
+mkdir -p "${DATA_DIR}"
+mv "${LEGACY}/timewarrior.cfg" "${CONFIG_DIR}"
+mv "${LEGACY}/extensions" "${CONFIG_DIR}"
+mv "${LEGACY}/data" "${DATA_DIR}"
+rmdir "${LEGACY}"
+----
+
 This file contains a mix of rules and configuration settings.
 Note that the TIMEWARRIORDB environment variable can be set to override this location.
 
diff --git a/doc/rules.txt b/doc/rules.txt
index 946384c4..958b95ff 100644
--- a/doc/rules.txt
+++ b/doc/rules.txt
@@ -1,12 +1,17 @@
 Rules System
 ============
-The Timewarrior rule system reads your ~/.timewarrior/timewarrior.cfg file and
+The Timewarrior rule system reads your timewarrior.cfg file and
 uses the combination of configuration settings and logic within to:
 
 - Define configuration and customization details
 - Define tags, exclusions, constraints
 - Define various policies
 
+On non-Unix systems config file is expected in ~/.timewarrior directory.
+On Unix systems, if legacy ~/.timewarrior directory doesn't exists, config is
+read from $XDG_CONFIG_HOME/timewarrior directory (if not specified,
+$XDG_CONFIG_HOME defaults to ~/.config).
+
 The rules are a mechanism to apply late-bound logic and data to various
 functions. Whenever data changes, the rule system is run, which will run each
 rule in turn, if it applies, going from top to bottom in the rules file. There
@@ -19,8 +24,8 @@ will initially be minimal, but grow to be come more capable.
 
 Format
 ------
-The rules are written as UTF8 text in the ~/.timewarrior/timewarrior.cfg text
-file. Other rules files may be included:
+The rules are written as UTF8 text in the timewarrior.cfg text file. Other
+rules files may be included:
 
   import /path/to/other/rule/file
 
diff --git a/doc/themes/README b/doc/themes/README
index 30bf5c8d..81d8f6a4 100644
--- a/doc/themes/README
+++ b/doc/themes/README
@@ -4,7 +4,8 @@ The theme files define colors that Timewarrior uses in various situations.
 There are several themes provided with Timewarrior, and you use a theme by importing it into your configuration file.
 Edit this file:
 
-    ~/.timewarrior/timewarrior.cfg
+    ~/.timewarrior/timewarrior.cfg (non-Unix systems or instalations using pre-XDG paths on Unix systems)
+    ${XDG_CONFIG_HOME:-$HOME/.config}/timewarrior/timewarrior.cfg (Unix systems)
 
 And add the import line, which looks like this: