原文連結 譯者：carvendy

Maven 文件風格指南

哪裡來的風格？

文件風格指南被建立與在我們很多的文件一致性和還應用最佳實踐的文件。標準已經開始和將會隨著時間不斷擴大基於這個建議到Maven 開發郵箱列表。社群就預設應該寫他們自己的文件。

不是每一個規則都只指南里，一個動機作為它存在的原因。引用擴充套件原始碼是被鼓勵的。

日期格

人們如何格式化日期在世界各地各不相同，有時使人們難以理解對方。解決這個問題的方法就是轉換為ISO-8601標準。

在我們的文件中的日期必須的標準的：

YYYY-MM-DD

YYYY是格林威治日期，MM是一年當中的月從1（1月）到12（12月），和DD是一個月中是天從01到31。

注：所有文件元資料應該尊重交流，從例項中給予APT文件：

------
     Guide To Maven Documentation Style
     ------
     Dennis Lundberg
     ------
     2008-07-03
     ------

引用

POM 片段

一個POM檔案必須使用兩個空間互相壓痕。因為POM片段是經常使用在文件為了顯示怎麼配置一些事情，這些片段不是很寬這是很重要。如果這很寬，將會使得頁面在小螢幕上很難閱讀。

當你使用XML片段作為你的文件的例子，你需要確定例子是可以替代的。一個使用者應該可以拷貝和貼上例子到自己的POM而不需要改變後面的內容。

你應該宣告所有父POM節點以提高理解。你可以使用省略（i.e…），如果你不想指定節點。

例子

下面的例子，是如何分佈管理Maven site是可配置的。

<project>
      ...
      <distributionManagement>
        <site>
          <id>apache.website</id>
          <url>scp://people.apache.org/www/maven.apache.org/</url>
        </site
 
>
      </distributionManagement>
      ...
    </project>

正如你上面可以看到的==<distributionManagement>== 節點的縮排(=兩個空格)，這==<site>節點的兩個縮排(=4個縮排)和<id>== 是縮排的3次(=6空格)

命名文件檔案

所有名字應該用(-)替換空格，比如給予的APT文件：

guide-documentation-style.apt

更新文件

好的練習更新日期（正確格式），當你更新文件文件。

寫的思考

這裡是一些關於英語規則，列印原料的指標: