内部讨论贴。源自我学了下docbook，想推销一下。
下面都是我的发言，同事们的没列上来。
第一贴：推销docbook
写道
转载 :
为什么要使用DocBook呢？
实现单一源文件维护
一个文档需要不同的格式输出，并不算罕见。因为今天用户的环境千差万别，用户习惯的文档格式也是五花八门，要想使得更广大的用户群能够阅读到您所提供的电子文档，同一内容的不同输出就变得非常重要。但这样就大大增加了文档维护的困难，为文档工程师带来沉重的负担，单一源文件维护（single- sourcing）就成了迫切的需要。
DocBook文档采用 SGML/XML 格式。开放的数据格式配合丰富的工具软件，让单一源文件维护成为了可能。
实现文档的版本控制
没有版本控制，软件研发的管理将处于一种作坊式的无序状态。而文档又何尝不是如此呢？
如果你问一个采用了版本控制系统的团队的开发人员，今天的代码和昨天的代码有什么不同，相信他会连一个增加的标点都会告诉你。而你要去问他，你的第二版的概要设计比第一版多了哪些东西，他可能就要支支吾吾了。这是什么原因造成的呢？
目前几乎所有的版本控制系统、代码比较程序，只能对纯文本进行完美的、增量的版本控制。而像WORD、PDF等格式的文档，是以二进制的形式存在的，难以实现各个副本之间的比较。而DocBook文档是存文本格式的文档，可以类似代码管理一样进行文档的版本控制。
IT企业的知识管理和文档管理
IT企业中的知识管理、文档管理关乎企业的发展和生存。试想处于知识经济前沿的IT企业如果没有了知识管理，必然造成知识老化，被新兴的企业淘汰；试想人员变动频繁的IT企业没有了文档管理，业务的连续性就会随着核心人员的离去而受到致命一击。
虽然大多数IT企业都对员工有着撰写各种文档的要求，但是大多数文档只是为应付领导而存在，一旦完成便束之高阁，不加维护，且难以维护，成为文件服务器中的数字垃圾。
DocBook文档由于能够进行版本控制，使得多人参与撰写和维护成为了可能。积极的参与一方面提高了文档的更新频率，另一方面提高了员工的参与意识和良好的知识管理的习惯。
个人知识积累、知识共享的好帮手
在知识经济的时代，知识就是资本，但是这个资本不能从天而降，需要靠不断的积累；知识有很强的时效性，需要不断的更新。IT行业的从业人员，更无时无刻不要面对新知识，需要解决新问题。如果只是简单的求新、求变，不注重知识的积累，那么当有一天对新鲜事物丧失兴趣或者无力追捧的时候，就是需要离开这个行业的时候了。这也是这个行业的一条流行用语意义之所在——“搞IT是在吃青春饭”。
IT行业需要新鲜血液没错，但它更需要经验丰富的领军人物。怎样才能让自己的职业生涯更加持久，我的答案是知识积累。DocBook作为技术文档的撰写模式，它的持久性、可维护性、可版本控制，使得它可以作为个人知识总结、积累的得力途径。
http://www.worldhello.net 就是我用DocBook技术建立的个人知识积累之所。通过本书，介绍给大家。
采用DocBook格式写文档的风险有多大？
一方面，是学习成本的忧虑。学习DocBook，就必然要学习SGML/XML的基础知识，熟悉DocBook DTD定义的元素。SGML/XML的学习要经历一条陡峭的学习曲线，可能会遇到一定的挫折。但是以我的经验，开始使用DocBook并不需要成为 SGML/XML专家，而且随着DocBook的使用，会加深对SGML/XML的理解。从实际入手学习XML这一今日之星，不能不说是意外的收获。
另一方面，是对应用软件的顾虑。诚然撰写DocBook文档，目前还没有像Word、WPS这样所见即所得的文档编辑工具，更多的是使用最简单的纯文本编辑工具，这可能吓跑好多人。撰写DocBook文档，就要改变撰写文档的方式，这是一关。DocBook文档是一种结构化的文档，表现形式并不是在文档撰写过程中需要考虑的，把文档撰写者从文档的格式化中解放出来，增加了文档格式的统一，也一定程度的减少了工作量。
采用DocBook格式的文档会不会过时
DocBook 格式的文档是纯文本的、结构化的，也是自解释的。相比二进制格式的文档，更易解析。我们可能遇到这样的情况：找出十年前的一个文档，发现它是基于某一个专有的文档编辑软件编写的二进制格式的文档，如果这种编辑软件现已不流行，甚至已经功成身退，你有信心能够顺利打开它么？这个文档可能就成了天书、数字垃圾。是否想过今天我们的WORD文档，十年后是否也会象今天一样潇洒的打开？再想象一下一百年后有个历史学家想要查找一个电子文档库，如果是诸如Word 的二进制文档，这些历史学家必须绞尽脑汁的去破解它们，这不会比破译口令更容易。
对于一个要长久保存的文档，一个易于理解的格式是多么的重要。大胆的使用DocBook来撰写你的文档，它能帮你写出传世之作。
为什么要使用DocBook呢？
实现单一源文件维护
一个文档需要不同的格式输出，并不算罕见。因为今天用户的环境千差万别，用户习惯的文档格式也是五花八门，要想使得更广大的用户群能够阅读到您所提供的电子文档，同一内容的不同输出就变得非常重要。但这样就大大增加了文档维护的困难，为文档工程师带来沉重的负担，单一源文件维护（single- sourcing）就成了迫切的需要。
DocBook文档采用 SGML/XML 格式。开放的数据格式配合丰富的工具软件，让单一源文件维护成为了可能。
实现文档的版本控制
没有版本控制，软件研发的管理将处于一种作坊式的无序状态。而文档又何尝不是如此呢？
如果你问一个采用了版本控制系统的团队的开发人员，今天的代码和昨天的代码有什么不同，相信他会连一个增加的标点都会告诉你。而你要去问他，你的第二版的概要设计比第一版多了哪些东西，他可能就要支支吾吾了。这是什么原因造成的呢？
目前几乎所有的版本控制系统、代码比较程序，只能对纯文本进行完美的、增量的版本控制。而像WORD、PDF等格式的文档，是以二进制的形式存在的，难以实现各个副本之间的比较。而DocBook文档是存文本格式的文档，可以类似代码管理一样进行文档的版本控制。
IT企业的知识管理和文档管理
IT企业中的知识管理、文档管理关乎企业的发展和生存。试想处于知识经济前沿的IT企业如果没有了知识管理，必然造成知识老化，被新兴的企业淘汰；试想人员变动频繁的IT企业没有了文档管理，业务的连续性就会随着核心人员的离去而受到致命一击。
虽然大多数IT企业都对员工有着撰写各种文档的要求，但是大多数文档只是为应付领导而存在，一旦完成便束之高阁，不加维护，且难以维护，成为文件服务器中的数字垃圾。
DocBook文档由于能够进行版本控制，使得多人参与撰写和维护成为了可能。积极的参与一方面提高了文档的更新频率，另一方面提高了员工的参与意识和良好的知识管理的习惯。
个人知识积累、知识共享的好帮手
在知识经济的时代，知识就是资本，但是这个资本不能从天而降，需要靠不断的积累；知识有很强的时效性，需要不断的更新。IT行业的从业人员，更无时无刻不要面对新知识，需要解决新问题。如果只是简单的求新、求变，不注重知识的积累，那么当有一天对新鲜事物丧失兴趣或者无力追捧的时候，就是需要离开这个行业的时候了。这也是这个行业的一条流行用语意义之所在——“搞IT是在吃青春饭”。
IT行业需要新鲜血液没错，但它更需要经验丰富的领军人物。怎样才能让自己的职业生涯更加持久，我的答案是知识积累。DocBook作为技术文档的撰写模式，它的持久性、可维护性、可版本控制，使得它可以作为个人知识总结、积累的得力途径。
http://www.worldhello.net 就是我用DocBook技术建立的个人知识积累之所。通过本书，介绍给大家。
采用DocBook格式写文档的风险有多大？
一方面，是学习成本的忧虑。学习DocBook，就必然要学习SGML/XML的基础知识，熟悉DocBook DTD定义的元素。SGML/XML的学习要经历一条陡峭的学习曲线，可能会遇到一定的挫折。但是以我的经验，开始使用DocBook并不需要成为 SGML/XML专家，而且随着DocBook的使用，会加深对SGML/XML的理解。从实际入手学习XML这一今日之星，不能不说是意外的收获。
另一方面，是对应用软件的顾虑。诚然撰写DocBook文档，目前还没有像Word、WPS这样所见即所得的文档编辑工具，更多的是使用最简单的纯文本编辑工具，这可能吓跑好多人。撰写DocBook文档，就要改变撰写文档的方式，这是一关。DocBook文档是一种结构化的文档，表现形式并不是在文档撰写过程中需要考虑的，把文档撰写者从文档的格式化中解放出来，增加了文档格式的统一，也一定程度的减少了工作量。
采用DocBook格式的文档会不会过时
DocBook 格式的文档是纯文本的、结构化的，也是自解释的。相比二进制格式的文档，更易解析。我们可能遇到这样的情况：找出十年前的一个文档，发现它是基于某一个专有的文档编辑软件编写的二进制格式的文档，如果这种编辑软件现已不流行，甚至已经功成身退，你有信心能够顺利打开它么？这个文档可能就成了天书、数字垃圾。是否想过今天我们的WORD文档，十年后是否也会象今天一样潇洒的打开？再想象一下一百年后有个历史学家想要查找一个电子文档库，如果是诸如Word 的二进制文档，这些历史学家必须绞尽脑汁的去破解它们，这不会比破译口令更容易。
对于一个要长久保存的文档，一个易于理解的格式是多么的重要。大胆的使用DocBook来撰写你的文档，它能帮你写出传世之作。
第二贴：
写道
主页
http://www.worldhello.net/doc/docbook_howto/index.html
我看它的主要优点 :
* 不需要关心排版.有几个人可以写出整齐漂亮复杂的word文档?
* 可以导出为html,pdf,chm,rtf,(自动分页,分段...)
* 可以使用cvs管理,
* 可以使用代码提示.
于WIKI的比较:
DocBook能写结构性强的计算机文档.Wiki比较随意零散.
Docbook导出能力强,wiki基本上要基于网站才能使用.
Docbook标准统一,wiki没有统一的标记标准.
与Word的比较:
不需要排版.
导出的文档风格统一,更加专业,
Spring,Hibernate等项目的漂亮文档都是用DocBook生成的.
http://www.worldhello.net/doc/docbook_howto/index.html
我看它的主要优点 :
* 不需要关心排版.有几个人可以写出整齐漂亮复杂的word文档?
* 可以导出为html,pdf,chm,rtf,(自动分页,分段...)
* 可以使用cvs管理,
* 可以使用代码提示.
于WIKI的比较:
DocBook能写结构性强的计算机文档.Wiki比较随意零散.
Docbook导出能力强,wiki基本上要基于网站才能使用.
Docbook标准统一,wiki没有统一的标记标准.
与Word的比较:
不需要排版.
导出的文档风格统一,更加专业,
Spring,Hibernate等项目的漂亮文档都是用DocBook生成的.
第三贴
写道
我觉得项目文档最重要的是
历史比较/恢复功能 ,
我每次改了开发文档,都必须把增加的部分用红字高亮,把删除的用删除线高亮,费力地调整版面布局,然后发布,并且通知每一个相关人员注意更新文档,这种繁琐程度是可以让人发疯的.而且这个文档还只能我一个人修改,否则同步问题是个大麻烦!
我的目标是一种可以用cvs管理的文档格式,所以必须是纯文本.而且语法结构要简单,否则没有人能直接从cvs diff中直接看出文档的变动,并很快学会怎么写并增加自己的反馈.
我想微软/google的产品目前都不会符合我的要求.(google的doc我很早就试用过了,是有版本功能的,而且能够协作开发,但它的在线性本质上不适合开发项目文档,微软的仅仅听说,没有了解,如果能够成为标准,倒也不错)
最简单的选择是纯文本的readme.txt文件,----可以满足简单的文档需求.
如果是复杂的项目文档,DocBook是合适的.
我每次改了开发文档,都必须把增加的部分用红字高亮,把删除的用删除线高亮,费力地调整版面布局,然后发布,并且通知每一个相关人员注意更新文档,这种繁琐程度是可以让人发疯的.而且这个文档还只能我一个人修改,否则同步问题是个大麻烦!
我的目标是一种可以用cvs管理的文档格式,所以必须是纯文本.而且语法结构要简单,否则没有人能直接从cvs diff中直接看出文档的变动,并很快学会怎么写并增加自己的反馈.
我想微软/google的产品目前都不会符合我的要求.(google的doc我很早就试用过了,是有版本功能的,而且能够协作开发,但它的在线性本质上不适合开发项目文档,微软的仅仅听说,没有了解,如果能够成为标准,倒也不错)
最简单的选择是纯文本的readme.txt文件,----可以满足简单的文档需求.
如果是复杂的项目文档,DocBook是合适的.
第四贴：
写道
公司里恐怕没有谁学习基本的html语法(无css)需要一个星期以上吧.这点学习成本可以不计.
基本的DocBook元素:
Book,Chapter,Article
anchor，link, ulink
itemizedlist, orderedlist, ...
itemizedlist, orderedlist, ...
Screen, programlist, co
emphsis, phrase, quote, system, filename, ...
faq
不会比html复杂多少.
很多时候,几个字的改动会有极大的影响. 譬如字段名写错了,为什么不能是一个新版本呢(而且貌似我们从来不管版本号,呵呵).版本管理方面,cvs能延续我们一贯的管理思路,功能也很强,为什么不用呢.
程序员写文档,给程序员看,我个人认为更应该注重的是内容而不是排版,(Wiki的成功就在于它的简化标记写法). 而且我也没见过公司有几个人的word能排得很整齐的.还记得那时候在大学里写论文,有专门一套样式,很规范漂亮,全校写的论文都一个样,可以直接打印出书,但用起来很麻烦.向css一样,把内容/表现分离开了不是更好吗?
QUOTE:
像你说的“Google Doc是有版本功能的,而且能够协作开发,但它的在线性本质上不适合开发项目文档”，你用什么来作为你最后一句话的依据呢
我觉得项目文档应该直接就包含在项目目录中,随着代码走.不管什么时候不管什么系统环境下都可以打开(比如在机房按照文档进行配置),在线的东西,总是有访问不到的情况的(当然,可以经常导出到本地,难道这个动作能比得上cvs的同步方便吗?也不能自动化).受网络环境影响较大,放在别人的服务器上总不如放在自己的服务器上让人放心,速度也可能成为问题.
基本的DocBook元素:
Book,Chapter,Article
anchor，link, ulink
itemizedlist, orderedlist, ...
itemizedlist, orderedlist, ...
Screen, programlist, co
emphsis, phrase, quote, system, filename, ...
faq
不会比html复杂多少.
很多时候,几个字的改动会有极大的影响. 譬如字段名写错了,为什么不能是一个新版本呢(而且貌似我们从来不管版本号,呵呵).版本管理方面,cvs能延续我们一贯的管理思路,功能也很强,为什么不用呢.
程序员写文档,给程序员看,我个人认为更应该注重的是内容而不是排版,(Wiki的成功就在于它的简化标记写法). 而且我也没见过公司有几个人的word能排得很整齐的.还记得那时候在大学里写论文,有专门一套样式,很规范漂亮,全校写的论文都一个样,可以直接打印出书,但用起来很麻烦.向css一样,把内容/表现分离开了不是更好吗?
QUOTE:
像你说的“Google Doc是有版本功能的,而且能够协作开发,但它的在线性本质上不适合开发项目文档”，你用什么来作为你最后一句话的依据呢
我觉得项目文档应该直接就包含在项目目录中,随着代码走.不管什么时候不管什么系统环境下都可以打开(比如在机房按照文档进行配置),在线的东西,总是有访问不到的情况的(当然,可以经常导出到本地,难道这个动作能比得上cvs的同步方便吗?也不能自动化).受网络环境影响较大,放在别人的服务器上总不如放在自己的服务器上让人放心,速度也可能成为问题.
最后没有结论 。
再后来过了几个月一致决定用wiki，公司开始把项目文档向wiki迁移。不过高层对如何写文档没有一个清晰和持续的政策，写了小半年，wiki也逐渐荒废，又回到不写文档的老路上，有需要就拉起word大干一场。囧！