什么工具/框架,用于技术文档?

我们开发产品和框架与我们的组织中使用。 我找程序员友好的文档工具。 我已经研究了几个选项的某个时候回来,但不能决定使用哪一个。 我期待从谁已经使用这些工具的人的建议。

  1. docbook的:springframework的和休眠使用这种格式,这看起来不错。 但我相信他们已经定制了默认的XSLT /样式表。 我可以复制和使用他们的XSLT和CSS(ofcourse颜色和图像的改变)。 我可以整合使用maven的文档生成?
  2. 维基:这不是友好的技术文档编写者和文档看起来不专业。 版本控制也是不可能的,我相信
  3. Word文档:这就是我们目前使用,但它是很难联系和重用共同文件。
  4. DITA?

--------------解决方案-------------

DocBook的

复制样式:是的,你可以复制和适应样式表。 对于DocBook XSL样式表是非常灵活的,但不容易理解。 你将不得不把一些日子,让他们的工作,你喜欢的方式。

Maven的集成:是的,有 Maven插件,你可以集成文档的生成(如PDF,HTML等)在构建过程中。 我们正在做的是,包括水印只快照和发布部署到archiva。

我很满意的DocBook虽然最初斜坡上升(包括调整样式表)不那么容易。 但是,一旦一切都做,它真的很容易使用。

我是从通过标准的XSLT任务的Ant build.xml文件运行的docbook我辈。 如果Maven的允许你调用XSLT处理器那么一切都应该罚款。

唯一的缺点(我发现)大书需要如何进行管理(以避免在一个单一的巨大的XML文件拥有一切)的方式

每章是一个单独的XML文件,这是不幸的是没有一个完整的DocBook文件,因为它被用通过系统的实体包括:

<?XML版本=“1.0”编码=“UTF-8”?>
<!DOCTYPE文章PUBLIC“ - // OASIS // DTD DocBook的XML V4.5 // EN”
“http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd”
[
<!ENTITY chapter_1 SYSTEM“chapter_1.xml”>
<!ENTITY chapter_1 SYSTEM“chapter_1.xml”>
]>

<?xml样式表的HREF =“html.css”类型=“文/ CSS”?>

<本文LANG =“EN”>
<标题>手动</ title>

&第1章;
&第2章;

</条>

然后chapter_1.xml看起来是这样的:

<节ID =“chapter_1”>
....
</>

有可能是更好的解决方案在那里,但我没有发现他们。)

同样的问题也相比发生在我们的项目。 到这一点,我们使用普通的HTML和Word文档,但这些方法都不能令人满意。

现在我们使用DITA,我真的推荐它。 它比DocBook的更轻巧,适用很好的软件文档。

一些优点:

  • DITA允许的内容和样式分离
  • 的内容和造型的分离允许生成用于不同的格式,例如HTML或PDF的文档。 例如,我们使用DITA生成我们的基于Eclipse RCP的应用程序的EclipseHelp。
  • DITA定义了软件特定的命名空间(如<input><menu-item>等)
  • DITA是与各种输出格式生成脚本,它可以很容易地适应您的特定需求提供。

另请参阅DITA开放工具包项目首页

不知道你是否正在寻找其它建议或您列出的只是反馈/范围缩小,但...

Python使用reStructuredText的Sphinx的,这是我已经开始在工作中采用并很享受一个工具链的组合。

你列出的,我已经使用维基前,这是不愉快了很多原因,其中一些你已经触及。 词似乎一个糟糕的选择太多; 出那些我会选择DocBook,但我还不是很了解,所以...

使用维基。

您的异议:

这不是友好的技术文档编写者和文档看起来不专业。 版本控制也是不可能的,我相信

有维基,让所见即所得的编辑。 一所房子内部项目技术文件并不需要“看起来很专业。” 全球版本是一个问题,但我不认为这是那么重要。

在另一方面,维基的巨型的好处是一个不能被看重高度不够,尤其是对企业内部产品:易贡献和协作。 该产品的每个用户都可以向文档,如果你可以在文档上建立协作文化,其结果不失为(直译)的十倍比一般的“按钮X可做了,按钮x做B”更有益的技术谁是不实际使用该产品生产的作家文件。 没有人需要这些。 人们需要“如何”指南,词汇,常见问题和解决方法。

维基启用和促进这种有益的合作。 “专业”的创作工具,访问限制和审批程序杀死它。

您还可以结合的方法:

  • 使用维基用于创作有所涉及,因为只有高科技的作家更多的人。 这样,如开发商或支持人员可以很容易地参与。
  • 有工具,有其不从维基转换至少DocBook的,如DocBook的维基或我公司的这的确从合流维基出口的DocBook并集成了DocBook的样式表滚动维基出口商(http://k15t.com/)延长定制(SE mhallers评论以上)含。 RenderX的XEP。

希望这可以帮助,

-Stefan

分类:java的 时间:2015-03-15 人气:0
分享到:

相关文章

Copyright (C) 55228885.com, All Rights Reserved.

55228885 版权所有 京ICP备15002868号

processed in 1.002 (s). 10 q(s)