Index: core/src/main/resources/org/apache/karaf/features/karaf-features-1.0.0.xsd
===================================================================
--- core/src/main/resources/org/apache/karaf/features/karaf-features-1.0.0.xsd	(revision 1205510)
+++ core/src/main/resources/org/apache/karaf/features/karaf-features-1.0.0.xsd	(working copy)
@@ -23,7 +23,7 @@
 
     <xs:annotation>
         <xs:documentation><![CDATA[
-Karaf features mechanism. For documentation please visit 
+Karaf features mechanism. For documentation please visit the
 <a href="http://karaf.apache.org/">Karaf website</a>.
         ]]></xs:documentation>
     </xs:annotation>
@@ -31,9 +31,9 @@
     <xs:complexType name="features">
         <xs:annotation>
             <xs:documentation><![CDATA[
-Root element of Feature definition. It contains optional attribute which allow
-name of repository. This name will be used in shell to display source repository
-of given feature.
+Root element of the Feature definition.  It contains an required attribute for
+designating from which repository this feature should be loaded.  The Karaf
+shell will show the repository name when displaying information about the feature. 
             ]]></xs:documentation>
         </xs:annotation>
         <xs:choice minOccurs="0" maxOccurs="unbounded">
@@ -65,7 +65,7 @@
             <xs:element name="details" minOccurs="0" type="xs:string">
                 <xs:annotation>
                     <xs:documentation><![CDATA[
-Long info displayed in features:info command result.
+The help text shown for this feature when using the features:info console command. 
                     ]]>
                     </xs:documentation>
                 </xs:annotation>
@@ -81,7 +81,7 @@
         <xs:attribute name="resolver" type="tns:resolver">
             <xs:annotation>
                 <xs:documentation><![CDATA[
-Karaf allow using dynamic resolvers.
+Optional alternative resolver to use for determining the list of bundles to install for a given feature.
                 ]]>
                 </xs:documentation>
             </xs:annotation>
@@ -89,7 +89,7 @@
         <xs:attribute name="install" type="tns:install">
             <xs:annotation>
                 <xs:documentation><![CDATA[
-Marks if the feaute will be automatically started when thrown to the deploy folder.
+If true, marks that the feature should start automatically when placed in the deploy folder. 
                 ]]>
                 </xs:documentation>
             </xs:annotation>
@@ -97,7 +97,8 @@
         <xs:attribute name="start-level" type="xs:int">
              <xs:annotation>
                 <xs:documentation><![CDATA[
-Bundles in this feature start level set to OSGi framework.
+Set this attribute to have an OSGI start level for this feature different 
+from the default start level defined in Karaf's config.properties.
                 ]]>
                 </xs:documentation>
              </xs:annotation>
@@ -115,7 +116,8 @@
                 <xs:attribute name="start-level" type="xs:int">
                     <xs:annotation>
                         <xs:documentation><![CDATA[
-Bundle start level set to OSGi framework.
+Set this attribute to have an OSGI start level for this bundle different 
+from the default start level defined in Karaf's config.properties.
                         ]]>
                         </xs:documentation>
                     </xs:annotation>
@@ -123,7 +125,7 @@
                 <xs:attribute name="start" type="xs:boolean" default="true">
                     <xs:annotation>
                         <xs:documentation><![CDATA[
-This switch allow you to leave bundle in resolved state rather than the default active state.
+If false, leaves bundle in resolved state rather than the default active state.
                         ]]>
                         </xs:documentation>
                     </xs:annotation>
@@ -131,7 +133,7 @@
                 <xs:attribute name="dependency" type="xs:boolean">
                     <xs:annotation>
                         <xs:documentation><![CDATA[
-Mark bundle as dependency for resolver.
+Mark this bundle as a dependency for the resolver.
                         ]]>
                         </xs:documentation>
                     </xs:annotation>
@@ -179,18 +181,17 @@
                 <xs:attribute name="finalname" type="xs:string" use="required">
                     <xs:annotation>
                         <xs:documentation><![CDATA[
-Name of file name where given deployable element should be stored.
+The final destination path and name for the configuration file.
                         ]]></xs:documentation>
                     </xs:annotation>
                 </xs:attribute>
-                <xs:attribute name="override" type="xs:boolean">
+                <xs:attribute name="override" type="xs:boolean" default="false">
                     <xs:annotation>
                         <xs:documentation><![CDATA[
-flag to specify if the finalname file should be overriden
+If the configFile already exists at the finalname location, whether or not to replace it.
                         ]]></xs:documentation>
                     </xs:annotation>
                 </xs:attribute>
-
             </xs:extension>
         </xs:simpleContent>
     </xs:complexType>
@@ -209,7 +210,7 @@
     <xs:simpleType name="resolver">
         <xs:annotation>
             <xs:documentation><![CDATA[
-Resolver to use. Karaf will look for OSGi servie which have following properties:
+Resolver to use. Karaf will look for OSGi service which has the following properties:
 objectClass: org.apache.karaf.features.Resolver
 name: the value
             ]]></xs:documentation>
@@ -221,7 +222,7 @@
     <xs:simpleType name="install">
         <xs:annotation>
             <xs:documentation><![CDATA[
-Installation mode. Can be either manual or auto. Specifies wether the feature should be automatically installed when
+Installation mode. Can be either manual or auto. Specifies whether the feature should be automatically installed when
 dropped inside the deploy folder. Note: This attribute doesn't affect feature descriptors that are installed from the
 command line or as part of the org.apache.karaf.features.cfg.
             ]]></xs:documentation>
@@ -230,6 +231,7 @@
             <xs:minLength value="1" />
         </xs:restriction>
     </xs:simpleType>
+
     <xs:element name="features" type="tns:features" />
 
 </xs:schema>