diff --git a/BUGS b/BUGS
new file mode 100644
index 0000000..3d4dd29
--- /dev/null
+++ b/BUGS
@@ -0,0 +1,8 @@
+ * only package names are matched, versions are not matched
+ * Gentoo packages are only mapped to Debian Source packages. This means that
+   you get a list of Debian source packages as build dependencies. Those
+   source packages have later to be mapped to binary packages.
+ * software in Gentoo that's not in Debian
+ * software in Debian that's not in Gentoo
+ * different source package splittings
+ * disjunctive dependencies not handled yet
diff --git a/README b/README
index 44c8a01..1a7f2f8 100644
--- a/README
+++ b/README
@@ -6,37 +6,21 @@ Then update your ./portdir with
 
 $ ./update-portdir.sh
 
-Optionally, you can refresh the content of reduced_gen_deps.list by running:
+At this point, you can already run the following script to get the list of
+Debian source packages that can be mapped to Gentoo packages and also have
+dependencies that can be dropped in Gentoo:
 
-$ ./gentoo_dep_list.py
+$ ./find_reduced.py
 
-It writes all source packages with reduced build dependencies plus the build
-dependencies that can be dropped to reduced_gen_deps.list. Execution takes
-about 2.5 hours.  
+It will print:
+  - a list of Debian source packages with dependencies that can be dropped
+  - a list of Debian packages that cannot be mapped to Gentoo packages
+  - a list of Gentoo packages that cannot be mapped to Debian packages
 
-Create the file gen_source_pkgs.list by running:
-
-$ ./gentoo_pkg_list_raw.sh
-
-This file contains a list of all gentoo packages in your ./portdir
-
-Once you have a filled reduced_gen_deps.list and gen_source_pkgs.list, check
-that deb_source_pkgs.list contains all Debian source packages that you are
-interested in.
-
-The file deb2gen_mapping.list maps Debian packages to Gentoo packages. 
-
-To inspect missing mappings from Debian source packages to Gentoo packages,
-run:
-
-$ ./find_pkg_matches.py
-
-It will print you a list of Debian packages that miss a mapping to Gentoo
-packages as well as a list of suggestions of Gentoo packages that sound
-similar.
-
-Lets summarize the data files that are present by now:
+Above script depends on the following data files to be present:
 
+portage               - portage sourcecode
+                          * retrieved as a git submodule
 portdir               - database of ebuild files
                           * retrieved by ./update-portdir.sh
 reduced_gen_deps.list - Gentoo packages with reduced dependencies
@@ -49,13 +33,21 @@ deb2gen_mapping.list  - mapping of Debian to Gentoo packages
                           * created manually and/or with the help of
                             ./find_pkg_matches.py
 
-At this point, run the following script to get the list of Debian source
-packages that can be mapped to Gentoo packages and also have dependencies that
-can be dropped in Gentoo:
+deb_source_pkgs.list is filled by the user. All other *.list files can be
+regenerated by the following scripts:
 
-$ ./find_reduced.py
+$ ./gentoo_dep_list.py
 
-It will print:
-  - a list of Debian source packages with dependencies that can be dropped
-  - a list of Debian packages that cannot be mapped to Gentoo packages
-  - a list of Gentoo packages that cannot be mapped to Debian packages
+   It writes all source packages with reduced build dependencies plus the build
+   dependencies that can be dropped to reduced_gen_deps.list. Execution takes
+   about 2.5 hours.  
+
+$ ./gentoo_pkg_list_raw.sh
+
+   It writes to gen_source_pkgs.list a list of all available Gentoo packages.
+
+$ ./find_pkg_matches.py
+
+   Inspects the current content of deb2gen_mapping.list and prints a list of
+   Debian packages that miss a mapping to Gentoo packages as well as a list of
+   suggestions of Gentoo packages that sound similar.