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.
