update docs and README.rst

README.rst

@@ -1,6 +1,6 @@
 twtxt
 ~~~~~
-|pypi| |build| |coverage| |docs| |gitter| |license|
+|pypi| |build| |coverage| |docs| |license|
 
 **twtxt** is a decentralised, minimalist microblogging service for hackers.
 
@@ -59,10 +59,6 @@ twtxt is released under the MIT License. See the bundled LICENSE file for detail
     :target: https://coveralls.io/r/buckket/twtxt?branch=master
     :alt: Test coverage
 
-.. |gitter| image:: https://img.shields.io/gitter/room/buckket/twtxt.svg?style=flat
-    :target: https://gitter.im/buckket/twtxt
-    :alt: Chat on gitter
-
 .. |license| image:: https://img.shields.io/badge/license-MIT-blue.svg?style=flat
     :target: https://raw.githubusercontent.com/buckket/twtxt/master/LICENSE
     :alt: Package license

docs/index.rst

@@ -24,11 +24,11 @@ User Guide
    user/configuration
    user/twtxtfile
    user/registry
+   user/discoverability
 
 Community
 ---------
 
-- twtxt gitter chat: https://gitter.im/buckket/twtxt
 - twtxt IRC channel: **#twtxt** on `irc.freenode.net`_
 
 API Reference

docs/user/configuration.rst

@@ -3,7 +3,10 @@
 Configuration
 =============
 
-twtxt uses a simple INI-like configuration file. It’s recommended to use ``twtxt quickstart`` to create it. On Linux twtxt checks ``~/.config/twtxt/config`` for its configuration. OSX uses ``~/Library/Application Support/twtxt/config``. Consult :func:`click.get_app_dir` to find out the config directory for other operating systems.
+twtxt uses a simple INI-like configuration file. It’s recommended to use ``twtxt quickstart`` to create it.
+On Linux twtxt checks ``~/.config/twtxt/config`` for its configuration.
+On OSX it uses ``~/Library/Application Support/twtxt/config``.
+Consult :func:`click.get_app_dir` to find out the config directory for other operating systems.
 
 Here’s an example ``conf`` file, showing every currently supported option:
 

docs/user/discoverability.rst

@@ -0,0 +1,28 @@
+.. _discoverability:
+
+Discoverability
+===============
+
+Because of the decentral nature of twtxt it can be hard to find new peers to follow, or even know who is following one’s own feed.
+The later being a problem because right now mentions only show up when you actively follow the feed the mention originated from.
+
+To solve this issue, besides the usage of :ref:`registries <registry>`, twtxt is using a specially crafted User-Agent string, when making outgoing HTTP requests.
+This then allows other users to search their webserver’s log file for those strings and find out who is consuming their content.
+
+.. note::
+
+    Implementing a so called linkback mechanism to actively notify someone explicitly about incoming mentions is currently `being discussed on GitHub <https://github.com/buckket/twtxt/issues/109>`_.
+
+The format twtxt is using is as follows:
+
+.. code::
+
+    twtxt/<version> (+<source.url>; @<source.nick>)
+
+For example:
+
+.. code::
+
+    twtxt/1.2.3 (+https://example.com/twtxt.txt; @somebody)
+
+Other clients are encouraged to use the same format.

docs/user/quickstart.rst

@@ -40,7 +40,7 @@ The quickstart wizard prompts for the following configuration values:
 - The desired location for your twtxt file (*<TWTXTX FILE LOCATION>*)
 - The URL your twtxt file will be accessible from remotely (*<TWTXT URL>*)
 - If you want to disclose your identity. If True your nick and URL will be used in the User-Agent
-  header attribute when fetching other twtxt files via HTTP.
+  header attribute when fetching other twtxt files via HTTP, see :ref:`discoverability`.
 - If you want to follow the official twtxt news feed
 
 The configurations can easily be changed in the twtxt configuration file. See :ref:`configuration`.

docs/user/registry.rst

@@ -1,4 +1,4 @@
-.. registry:
+.. _registry:
 
 Registry
 ========

docs/user/twtxtfile.rst

@@ -9,7 +9,7 @@ The location of the twtxt file is configured in the twtxt section in the configu
 Format specification
 --------------------
 
-The twtxt file contains one status per line, each of which is equipped with an RFC 3339 date-time string followed by a TAB character (\\t) to separate it from the actual text. A specific ordering of the statuses is not mandatory.
+The twtxt file contains one status per line, each of which is equipped with an RFC 3339 date-time string (with or without UTC offset) followed by a TAB character (\\t) to separate it from the actual text. A specific ordering of the statuses is not mandatory.
 
 The file must be encoded with UTF-8 and must use LF (\\n) as line separators.