diff --git a/conftest.py b/conftest.py
index a0c1520..e698a7b 100644
--- a/conftest.py
+++ b/conftest.py
@@ -1,5 +1,5 @@
 """
-configuration for the tests
+configuration for the (py.test based) tests
 """
 
 import pytest
diff --git a/nsupdate/api/views.py b/nsupdate/api/views.py
index b58098d..7343a5f 100644
--- a/nsupdate/api/views.py
+++ b/nsupdate/api/views.py
@@ -1,4 +1,7 @@
 # -*- coding: utf-8 -*-
+"""
+views for the (usually non-interactive, automated) web api
+"""
 
 import logging
 logger = logging.getLogger(__name__)
diff --git a/nsupdate/context_processors.py b/nsupdate/context_processors.py
index c7adf37..6fb8f3b 100644
--- a/nsupdate/context_processors.py
+++ b/nsupdate/context_processors.py
@@ -1,4 +1,8 @@
 # -*- coding: utf-8 -*-
+"""
+context processors for injecting some settings into the template context and
+also for keeping the IP addrs in the session fresh.
+"""
 
 import logging
 logger = logging.getLogger(__name__)
diff --git a/nsupdate/main/admin.py b/nsupdate/main/admin.py
index 033cbc1..ef3c134 100644
--- a/nsupdate/main/admin.py
+++ b/nsupdate/main/admin.py
@@ -1,3 +1,7 @@
+"""
+register our models for Django's admin
+"""
+
 from django.contrib import admin
 
 from .models import Host, Domain, BlacklistedDomain, ServiceUpdater, ServiceUpdaterHostConfig
diff --git a/nsupdate/main/forms.py b/nsupdate/main/forms.py
index ae41d31..bec7df7 100644
--- a/nsupdate/main/forms.py
+++ b/nsupdate/main/forms.py
@@ -1,4 +1,8 @@
 # -*- coding: utf-8 -*-
+"""
+form definitions (which fields are available, order, autofocus, ...)
+"""
+
 from django import forms
 
 from .models import Host, Domain, ServiceUpdaterHostConfig
diff --git a/nsupdate/main/models.py b/nsupdate/main/models.py
index 590a6b7..af12e57 100644
--- a/nsupdate/main/models.py
+++ b/nsupdate/main/models.py
@@ -1,3 +1,7 @@
+"""
+models for hosts, domains, service updaters, ...
+"""
+
 import re
 import base64
 
diff --git a/nsupdate/main/urls.py b/nsupdate/main/urls.py
index 4334c6a..c7cb51c 100644
--- a/nsupdate/main/urls.py
+++ b/nsupdate/main/urls.py
@@ -1,3 +1,7 @@
+"""
+main app url dispatching
+"""
+
 from django.conf.urls import patterns, url
 from django.views.generic import TemplateView
 
diff --git a/nsupdate/main/views.py b/nsupdate/main/views.py
index a4bcefb..0f13597 100644
--- a/nsupdate/main/views.py
+++ b/nsupdate/main/views.py
@@ -1,4 +1,7 @@
 # -*- coding: utf-8 -*-
+"""
+views for the interactive web user interface
+"""
 
 from datetime import timedelta
 
diff --git a/nsupdate/management/commands/faults.py b/nsupdate/management/commands/faults.py
index 3a5b906..f6f498f 100644
--- a/nsupdate/management/commands/faults.py
+++ b/nsupdate/management/commands/faults.py
@@ -1,5 +1,5 @@
 """
-reinitialize the test user account (and clean up)
+dealing with the fault counters and available/abuse/abuse_blocked flags
 """
 
 from optparse import make_option
diff --git a/nsupdate/urls.py b/nsupdate/urls.py
index 975a14c..a69b34e 100644
--- a/nsupdate/urls.py
+++ b/nsupdate/urls.py
@@ -1,3 +1,7 @@
+"""
+top-level url dispatching
+"""
+
 from django.conf import settings
 from django.conf.urls import patterns, include, url
 from django.contrib import admin