diff --git a/README b/README
deleted file mode 100644
--- a/README
+++ /dev/null
@@ -1,28 +0,0 @@
-KContacts - new address book API for KDE
-
-PURPOSE:
-
-KCcontacts provides an API for address book data. This can be used by all
-application using data of this type, e.g. KAddressBook, KMail, KOrganizer,
-etc. 
-
-FEATURES:
-
-- Value based interface, addressbook entry data is implicitly shared.
-- Address book entries are identified by a unique id.
-- vCard backend (RFC 2425 / RFC 2426).
-- Locking mechanism to support concurrent access to the address book by
-  multiple processes.
-- Notification on change of addressbook by other process.
-- Dialog for selecting address book entries, supports mouse and keyboard
-  selection, supports automatic name completion.
-- GUI client for viewing, modifying address book data. This is aimed at
-  developers not end users.
-- Tool for converting data, written with libkab, to libkabc format.
-- Multiple backends (resources) for storing entries e.g. LDAP
-
-AUTHOR: Cornelius Schumacher <schumacher@kde.org>
-
-LICENCE: LGPL
-
-DATE: 13 Oct 2001
diff --git a/README.md b/README.md
--- a/README.md
+++ b/README.md
@@ -1,3 +1,11 @@
-# KContact
+# KContacts
 
-KContact library provides vcard support
+KContact provides an API for contacts/address book data following the
+vCard standard (RFC 2425 / RFC 2426).
+
+## Features
+- vCard data model (see KContacts::Addressee).
+- vCard input/output (see KContacts::VCardConverter).
+- Contact group management (see KContacts::ContactGroup).
+- Locale-aware address formatting (see KContacts::Address).
+- Localized country name to ISO 3166-1 alpha 2 code mapping and vice verca (see KContacts::Address).
diff --git a/README.AddressFormat b/docs/AddressFormat.md
rename from README.AddressFormat
rename to docs/AddressFormat.md
--- a/README.AddressFormat
+++ b/docs/AddressFormat.md
@@ -1,3 +1,5 @@
+# Localized Address Formats
+
 Address formats can be a tricky thing. KContacts tries very hard to perfectly fit
 the needs of ~95% of users and to be at least sufficient for the other 5%.
 
@@ -26,8 +28,9 @@
 
 -Jost.
 
-Fields AddressFormat and BusinessAddressFormat
-------------------------------------------------
+## Fields AddressFormat and BusinessAddressFormat
+
+```
 %n  = real name
 %N  = REAL NAME
 %cm = company
@@ -49,16 +52,18 @@
       address doesn't have a postbox, the string %0(PO Box %p) will not 
       evaluate to "PO Box " but to an empty string.
 \n  = newline
+```
 
-Field AddressCountryPosition
-------------------------------------------------
+## Field AddressCountryPosition
+```
 below = country name below rest of address
 BELOW = country name below in capital letters
 above = country name above rest of address
 ABOVE = country name above in capital letters
+```
+
+## Some Tips
 
-Some Tips
-------------------------------------------------
 - You sometimes have three fields in a line which can all be empty. If you eg.
 separate them all with conditional whitespace (same goes for cond. comma) like
 in "%z%w%r%w%l" and only the middle value (here: region) is empty, there will
diff --git a/metainfo.yaml b/metainfo.yaml
--- a/metainfo.yaml
+++ b/metainfo.yaml
@@ -1,6 +1,6 @@
 maintainer: mlaurent
 description: Address book API for KDE 
-tier: 3
+tier: 2
 type: functional
 public_lib: true
 group: kdepim
diff --git a/src/addresseelist.h b/src/addresseelist.h
--- a/src/addresseelist.h
+++ b/src/addresseelist.h
@@ -265,11 +265,11 @@
 } SortingCriterion;
 
 /**
- * @short  a QValueList of Addressee, with sorting functionality
+ * @short  a QVector of Addressee, with sorting functionality
  *
- * This class extends the functionality of QValueList with
+ * This class extends the functionality of QVector with
  * sorting methods specific to the Addressee class. It can be used
- * just like any other QValueList but is no template class.
+ * just like any other QVector but is no template class.
  *
  * An AddresseeList does not automatically keep sorted when addressees
  * are added or removed or the sorting order is changed, as this would