加载中…
个人资料
NightWriter
NightWriter
  • 博客等级:
  • 博客积分:0
  • 博客访问:10,078
  • 关注人气:44
  • 获赠金笔:0支
  • 赠出金笔:0支
  • 荣誉徽章:
相关博文
推荐博文
谁看过这篇博文
加载中…
正文 字体大小:

docbook转DITA实践

(2012-10-27 16:49:33)
分类: 项目管理

  近期的一个项目是把一些遗留内容从docbook转成DITADarwin Information Typing Architecture)。DITA的好处不言面喻,一方面可以改善读者的阅读体验(按内容性质归类可以帮助读者更快地找到所需内容);另一方面也可以提高写作效率(模块化写作,内容重用等)。格式的转换并不是全部,还需要从更高的层次去改进文档的架构,这才是真正的目的。为此,我尝试性地做了一个小项目。


项目开始前要考虑的问题

1、 哪些内容需要做转换?

并不是所有的内容都需要转换。已经固化的内容可以继续延用;有的内容可以考虑更好的形式,如可以从代码自动生成一些参考文档。

2、 原来的内容需不需要重新设计和改写?

一般都需要重新审视文档结构。例如,如果原来的文档是基于章节(chapter)的,或者章节之间耦合太紧密等,都需要重新设计。

3、 采取什么样的策略?

a.       用什么工具进行转换?

分两头做:内容架构(DITAMAP)重新设计;文档内容转换后再编辑。由于编辑工具是Adobe FrameMaker,采用其自带的转换表格工具(conversion table)来进行转换。

b.      如何处理转换内容和新开发内容之间的关系,怎样才能不影响当前开发的进度?

新加的内容(无论转换与否)按新架构来写作,以减少未来转换的工作量。了解产品的发布计划,把转换工作放在两次发布之间进行。

 

c.       转换内容的优先顺序

经常使用->较少使用,改动频率大->改动频率小,内容新->内容旧

d.      是找外包公司来做还是自己做?时间如何分配?

还不确定外包公司有没有这样的业务。自己抽零碎时间做。

e.      内容管理:采用什么CMSContent Management System)?或者转换后文件采用怎样的命名规则?如何进行内容重用?

 

pilot项目

在考虑了这些问题后,按照以下步骤做了一个小项目:

1、 内容重设计

这也许是最重要也最容易被忽略的环节。在这个过程中,可能会发现一些缺失的内容。

a.       最好再确认用户场景和用例。虽然比较费时间,可以避免一着不慎,满盘皆输的局面。

b.      场景确认好后开始设计DITAMAP。推荐一个同行推荐的工具:IBM Information Architecture Workbench。可以由DITAMAP直接创建每个TOPICXML文件,在转换完成后把内容拷贝到各个XML文件中去。

c.       细化DITAMAP:考虑条件控制的内容(conditional text),设计关系表格(relationship table)等。

2、 原文档调整

为减少转换的工作量,需要对原文档进行调整。例如,调整章节结构、删去无用的内容。

有一些特殊内容需要做特别的处理,例如:

a.       步骤放在表格里

b.      交叉链接(为更好地重用内容,尽量不要在topic中插入链接,最好使用关系表格)

3、 定制DITA结构

(可选)根据需求定制DITA

4、 内容转换(要求熟悉DITA的标签规则)

用工具转换并不需要花太多时间。主要花费的时间在于修改和完善转换表格。

5、 内容清理(要求熟悉DITA的标签规则)

转换好的内容不能直接使用,还需要清理并完善。

6、 调整格式

按照公司风格调整模板格式。FMDITA模板位于:$FM_PATH\Structure\xml\DITA_1.2\app\technicalContent\template

7、 内容发布

可以使用FM直接发布成PDF。也可以通过RoboHelp发布成其它各种格式(HTML, EclipseHelp等)。

8、 解决问题

FrameMakerDITA的支持并不完美,转换和发布过程中可能会出现各种问题。所以需要预留一些troubleshooting的时间。


项目输出

项目完成后,有以下的输出:

1、 转换表格

2、 定制的DITA模板

3、 DITA标签使用规范(特别是针对定制的标签)

4、 问题解决方法和最佳实践方法的记录

5、 各环节工作量及时间记录

 

 

 

 

pilot项目的经验是整个转换项目的基础。在此基础上做项目计划和实施会容易一些。所以,这仅仅只是一个开始。

0

阅读 评论 收藏 转载 喜欢 打印举报/Report
  • 评论加载中,请稍候...
发评论

    发评论

    以上网友发言只代表其个人观点,不代表新浪网的观点或立场。

      

    新浪BLOG意见反馈留言板 电话:4000520066 提示音后按1键(按当地市话标准计费) 欢迎批评指正

    新浪简介 | About Sina | 广告服务 | 联系我们 | 招聘信息 | 网站律师 | SINA English | 会员注册 | 产品答疑

    新浪公司 版权所有