原文链接 译者：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
     ------

引用

• W3C 高质量网站技巧
• ISO-8601
• 维基百科

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

更新文档

好的练习更新日期（正确格式），当你更新文档文档。

写的思考

这里是一些关于英语规则，打印原料的指针:

• 维基：风格手册，明确地标点符号的一部分。
• 语言风格指南，明确地“语法指南”章节。