Index: docs/modelforms.txt
===================================================================
--- docs/modelforms.txt	(revision 8235)
+++ docs/modelforms.txt	(working copy)
@@ -262,7 +262,9 @@
 
 2. Use the ``fields`` attribute of the ``ModelForm``'s inner ``Meta``
    class.  This attribute, if given, should be a list of field names
-   to include in the form.
+   to include in the form. Note that this attribute also changes the
+   order in which fields are displayed in the resulting form (see 
+   below).
 
 3. Use the ``exclude`` attribute of the ``ModelForm``'s inner ``Meta``
    class.  This attribute, if given, should be a list of field names
@@ -339,6 +341,25 @@
    ...     class Meta:
    ...         model = Article
 
+Customizing field order
+-------------------------------
+
+By default django will show the model's fields first, followed by any form-
+specific fields. When you define the  ``field`` attribute of the 
+``ModelForm``'s inner ``Meta`` class, that order will be used::
+   
+   >>> Class CustomAuthor(ModelForm):
+   ...     pseudonym = CharField()
+   ...     
+   ...     class Meta:
+   ...         model = Author
+   ...         fields = ('name', 'pseudonym', 'birth_date')
+
+This will render a form with the pseudonym field in between name and birth_date.
+You can declare model fields, new fields and overridden fields in the ``fields``
+attribute.
+
+
 Form inheritance
 ----------------