svn commit: r673783 - /maven/site/trunk/src/site/apt/guides/development/guide-documentation-style.apt

[vs...@apache.org]

Author: vsiveton
Date: Thu Jul  3 13:01:54 2008
New Revision: 673783

URL: http://svn.apache.org/viewvc?rev=673783&view=rev
Log:
o small updates

Modified:
    maven/site/trunk/src/site/apt/guides/development/guide-documentation-style.apt

Modified: maven/site/trunk/src/site/apt/guides/development/guide-documentation-style.apt
URL: http://svn.apache.org/viewvc/maven/site/trunk/src/site/apt/guides/development/guide-documentation-style.apt?rev=673783&r1=673782&r2=673783&view=diff
==============================================================================
--- maven/site/trunk/src/site/apt/guides/development/guide-documentation-style.apt (original)
+++ maven/site/trunk/src/site/apt/guides/development/guide-documentation-style.apt Thu Jul  3 13:01:54 2008
@@ -3,12 +3,11 @@
  ------
  Dennis Lundberg
  ------
- 2008-06-26
+ 2008-07-03
  ------
 
 Guide To Maven Documentation Style
 
- 
 * Where did the style came from?
 
   The documentation style guide was created to make our documentation more
@@ -16,40 +15,49 @@
   The standard has just been started and will expand over time based on the
   suggestions made on the Maven dev mailing list. It is a community consensus
   of how we should write our documentation.
- 
+
   Each rule in this guide should come with a motivation as to why it exists.
   References to external sources are encouraged.
 
-  
 * Date format
 
   How people format a date varies around the world, sometimes making it hard
   for people to understand each other. The solution to this problem comes in
   the form of the ISO-8601 standard.
-  
+
   A date in our documentation must follow this standard:
-  
+
   <<YYYY-MM-DD>>
 
   where <<YYYY>> is the year in the Gregorian calendar, <<MM>> is the month of
   the year between 01 (January) and 12 (December), and <<DD>> is the day of the
   month between 01 and 31.
 
+ <<Note>>: All documentation meta-data should respect this convention, for instance for this given APT document:
+
++-----+
+ ------
+ Guide To Maven Documentation Style
+ ------
+ Dennis Lundberg
+ ------
+ 2008-07-03
+ ------
++-----+
+
 ** References
-  
+
   * {{{http://www.w3.org/QA/Tips/iso-date}W3C Quality Web Tips}}
-  
+
   * {{{http://www.iso.org/iso/iso_catalogue/catalogue_tc/catalogue_detail.htm?csnumber=26780}ISO-8601}}
 
   * {{{http://en.wikipedia.org/wiki/ISO_8601}Wikipedia}}
-  
-  []
 
+  []
 
 ~~ NOTE: Add more rules here. Follow the heading style of the rule above.
 
-
-* POM indentation
+* POM Snippet
 
   A POM file must use 2 spaces for each indentation. Because POM snippets are
   often used in documentation to show the user how to configure something, it is
@@ -61,20 +69,39 @@
   A user should be able to copy and paste the example into their own POM without
   the need to change the indentation afterwards.
 
+  Also, you should declare all parent POM elements to improve the comprehension. You could use ellipsis (i.e. ...) is
+  you don't want to specify elements.
+
 ** Example
 
   The following is an example of how the distribution management of the Maven
   site is configured.
 
-+-----
++-----+
+<project>
+  ...
   <distributionManagement>
     <site>
       <id>apache.website</id>
       <url>scp://people.apache.org/www/maven.apache.org/</url>
     </site>
   </distributionManagement>
-+-----
+  ...
+</project>
++-----+
 
   As you can see above the <<<\<distributionManagement\>>>> element is indented
   once (=2 spaces), the <<<\<site\>>>> element in indented twice (=4 spaces) and
   the <<<\<id\>>>> is indented three times (=6 spaces).
+
+* Naming Documentation Files
+
+ All file names should replace space by a minus (-), for instance for this given APT document:
+
++-----+
+ guide-documentation-style.apt
++-----+
+
+* Updating Documentation Files
+
+ A good practice is to update the date (with the correct date format) when you are updating documentation files.