使用 developerWorks Word 和 Writer 模板写作

指导作者编写和发表 developerWorks 文章和教程的逐步指南

欢迎作者们!本篇文章将向您展示如何使用 Microsoft® Word 或 OpenOffice.org Writer 为 developerWorks 中国网站创作技术文章和教程。所需步骤很简单。首先下载针对 Word 或 Writer 的模板,然后填写模板中的字段,最后根据模板中的指导完成文章或教程。本文还包括一些排版以及将其提交给 developerWorks 工作人员的小技巧。

Ian Shields, 高级程序员, IBM developerWorks

Ian Shields 博士为 developerWorks Linux 专区的许多 Linux 项目工作。他是在北卡罗来纳 Research Triangle Park 工作的 IBM 高级程序员。他于 1973 年在澳大利亚堪培拉作为系统工程师加入 IBM 公司,从那以后他在加拿大蒙特利尔和北卡罗来纳 RTP 从事通信系统和普及计算。他拥有几项专利。他从 Australian National University 获得了纯数学和哲学学位。他拥有 North Carolina State University 的计算机科学硕士和博士学位。



2007 年 11 月 15 日

希望使用 XML 模板而非 Word 处理程序模板?

如果您更喜欢用 XML 格式编排自己的文章,我们亦提供了 XML 模板供您使用。可以参阅本文的姊妹篇 “使用 developerWorks XML 模板写作”。

入门

developerWorks 的编辑们期待与您共同努力来发表您的文章。请确保您已经阅读过 developerWorks 投稿指南中的信息,并已经使用我们的 内容提交表格 来提交您的想法,并在使用本文中的这些指导完成写作之前已经获得他或她的同意。这些都将帮助我们以最快的速度处理您的稿件

文章和教程在 developerWorks 上是以 HTML 格式发布的,但其生成的格式是 XML(Extensible Markup Language)。developerWorks 的编辑具有将 Microsoft Word 和 OpenOffice.org Writer 文件转换为 XML 源格式的工具。转换成 XML 成功与否取决于所提交的 Word 或 Writer 文档是否严格遵从所使用模板的指导原则。

如果您对 Word 处理程序的样式很熟悉,就会发现我们的模板用起来很容易。如果不熟悉,我们的模板中亦包含详细的说明,解释了如何应用样式以符合本文描述的 排版技巧突出显示约定


文章还是教程?

如果曾经浏览过 developerWorks 站点, 就会知道作者既可以为 developerWorks 提供文章也可以为之提供教程。二者的格式和目的不同。developerWorks 编辑可以帮助您决定哪一种格式更适合您的内容和想法。

教程

  • 教程具有培训的目的;它们旨在教授。与简单地列出操作步骤相反,教程会解释为什么要执行这一步以及它与总目标的关系。教程一般会清楚地说明其教育目的和完成时间(通常大约两个小时)。学完某个教程后,读者就应该能够独立地重复完成所学的任务。
  • 教程可以教授概念,也可以教授如何完成任务。很多教程既教授概念又教授任务,并会鼓励读者在阅读时试着完成任务。为了便于学习,教程中经常会包含示例代码和有关读者环境的设置建议。教程还经常会将整块的内容分离成多个单独的可管理的任务。
  • 阅读教程需要注册。
  • 教程打印出来平均有 20 到 30 页。因为任务通常需要几个小时才能完成,很多读者会把教程打印出来,用以在执行任务或完成任务时参考。
  • 教程可以是独立的,也可以作为系列教程中的一部分。

文章

  • 与教程一样,文章也是教授,但教授的并不像教程那样直白。文章不会清楚地说明其教授目的和学习时间。
  • 除指导读者完成某个具体任务外,文章也可以介绍新概念、架构或是产品特性。这类文章的目的是为了引起读者的注意和激发他们进一步学习的兴趣(或许需要通过选修某个 developerWorks 教程!)。其中有一些文章具较强的说服力,作者拿出他或她独特的方法、观点或经验与读者分享。还有一些文章通过采访某位专家或回顾与某主题相关的资料来深入介绍一种新产品或技术。
  • 阅读文章不需要注册。
  • 文章打印出来通常只有 10 页甚至可能更少。读者一般都习惯在线阅读文章。
  • 与教程一样,文章也可以是独立的,可以作为系列文章中的一部分。

基本步骤

创建一个文章或教程要经过以下步骤:

  1. 下载针对 Word 或 Writer 的作者工具包(请参看本文后面的 下载 部分)并解压缩此文件。
  2. 通过借助模板文件或复制示例文章或教程,在 Word 或 Writer 内创建自己的文章或教程模板。
  3. 编辑新文章或教程,添加所需内容,但要确保符合模板或示例中的指导原则。
  4. 将文章或教程与其他文件(如图片或代码)一起发送给 developerWorks 编辑。

步骤 1. 下载作者工具包

如果使用的是 Windows® 系统上的 Word,需要下载 Word 作者工具包 zip 文件,如果使用的是 Windows 或 Linux® 系统上的 OpenOffice.org Writer,需要下载 Writer 作者工具包 zip 文件。将此文件放在一个合适的位置(比如,Windows 中的 C:\ 或 Linux 中的根目录)并解压缩此文件。

在解压缩文件后,将会看到一个 developerworks 目录(或文件夹),内含一个 word-templateswriter-templates 子文件夹,究竟是哪个子文件夹取决于所下载的作者工具包。

作者工具包中所包含的这些文件或工具是为在 Linux 或 Windows 中使用而设计的。如果使用的是 Windows 或 Linux 以外的其他操作系统,可以联系 developerWorks 编辑 获取帮助。


步骤 2. 创建文章或教程

在这一步,将从一个模板或示例开始构建自己的文章或教程。模板和示例包括了在 developerWorks 投稿时所能用到的大多数文档元素的样例,比如如何实现正确的格式和如何应用合适的样式。

模板
如果您是一个有丰富经验的 developerWorks 作者,可能更愿意采用模板。若采用模板,在显示指导资料之前,系统会提示您在几个字段中提供 developerWorks 的必要信息(参见 表 2)。
示例
如果您是一个 developerWorks 新手,我们建议您使用示例文章或教程。有了示例,您就能够立即开始构建文章的内容。developerWorks 的必要信息将被填上默认值,所以,在将内容发送给编辑前,需要更新这些字段。

要创建自己的文章或教程,打开表 1 中列出的相应文件。

表 1. 文章和教程模板和示例
模板或 示例程序文章或 教程文件
示例Microsoft Word文章sample-article-word-5.8.doc
教程sample-tutorial-word-5.8.doc
OpenOffice.org Writer文章sample-article-writer-5.8.odt
教程sample-tutorial-writer-5.8.odt
模板Microsoft Word文章article-word-5.8.dot
教程tutorial-word-5.8.dot
OpenOffice.org Writer文章article-writer-5.8.ott
教程tutorial-writer-5.8.ott

第一次打开模板时,需要填写表 2 中所示的字段。如果暂时还没有这些信息,您尽可以使用它们的默认值,以后再进行更新。

表 2. 要填写的提交字段
字段可选或 必需内容
日期必需撰写文章内容的日期。
提交的类型必需文章或教程,从下拉菜单中选择。
标题必需文章或教程的标题。
子标题可选文章或教程的子标题。可选但推荐。
关键字可选文章或教程的搜索引擎关键字。
前缀可选名字的前缀。示例: Dr.、Mr. 或 Ms。
必需您的姓名。示例: 李明。
中名无需填写您的中名或中名的首字母。示例: D。
无需填写姓氏。
后缀可选您名字的后缀。示例: Jr. 或 IV。
职位必需您的职位。示例: 高级程序员。
电子邮件必需您的电子邮件地址。
个人简介必需您对自己的简单介绍。最好表明自己的经验以及能够就这一主题发表文章的权威性。
公司必要公司的名称。示例:IBM。
照片文件名可选适合连同个人简介一起显示的 “头到肩” 照片的文件名。
摘要必要您文章的摘要。把文章的要点和关键术语放在摘要的开始处,因为摘要会在搜索结果中被截短。用三到五句话说说为什么读者要关注文章的内容(动机)以及他或她看完文章后能得到什么(收获)。

可以使用任意您喜欢的名字保存新文档。如果是从模板开始创建的,请确保将其保存为常规文档(.doc 对应 Word,.odt 对应 Writer)而不是保存为模板。


步骤 3. 编辑文章或教程

编辑文章或教程需要遵从示例文章或教程中的指导原则。这些指导原则展示了应该使用何种样式才能成功完成到 developerWorks XML 格式的转变。根据这些指导原则格式化内容是非常重要的

排版技巧

表 1 中给出的示例文件是获得全面的文章或教程编写技巧的最佳资源。示例中大量的注释对编写文章或教程的各个方面提供了指导。下面列出了其他一些有用的技巧 :

  • 可以从已有的其他文件中剪切和粘贴。但需要对比粘贴文本所导入的样式,看是否与我们的示例相匹配。
  • 这些示例包含了 developerWorks 文章和教程中经常使用的结构样例。如果您的内容不需要任何清单或图这类的东西,那么就不要因为示例中有这类内容而将自己不需要的东西添加到文章或教程中。
  • 当需要包含示例代码的清单时:
    • 将代码行的长度限制在 90 个字符以内,包括空格。
    • 要避免在示例代码行的结尾用硬编码空格或制表符。
    • 避免在示例代码行的开始使用制表符。如果必须要有缩进,请使用空格。
    • 不要使用颜色。如果想要突出显示示例代码中的某部分,请使用粗体。
  • 当提供可下载的示例代码时,请将代码打包并发给编辑。
  • 用.jpg 或 .gif 格式创建图形文件,包括屏幕截屏,并要确保图形的宽度不超过 572 像素(用于文章)或 500 像素(用于教程)。将图形文件发送给编辑。有关如何创建和提交有效图形的更多信息,请参阅 “developerWorks 投稿图片处理”。

突出显示的约定

书的标题使用斜体还是引号?究竟何时需要使用粗体 — 何时又根本无需进行任何突出显示呢?表 3 给出了 developerWorks 文章和教程推荐使用的突出显示约定。

表 3. 推荐的突出显示
突出显示的元素推荐的突出显示
“文章标题”引号
书的标题斜体
C/C++ 代码Courier 或 Courier New 字体
Courier 或 Courier New 字体
代码示例
HTML 预格式化的样式(Courier 或 Courier New 字体,8pt)
正文中引用的代码片段(少于一行)Courier 或 Courier New 字体
专栏或系列的名称斜体
命令的名称Courier 或 Courier New 字体
目录的名称无突出显示
强调斜体。例如:“使用 that 来引入一个限定性从句。 要输入……"
异常的名称Courier 或 Courier New 字体
文件的名称无突出显示
函数调用Courier 或 Courier New 字体
GUI 控件粗体。例如,“在 Installation 菜单,单击 Install a new feature > Finish。”
HTML 标记或节的示例Courier 或 Courier New 字体
界面Courier 或 Courier New 字体
关键字(比如 static)Courier 或 Courier New 字体
杂志的标题斜体。例如 “参见 LinuxToday 上的相关文章。”
消息文本或给用户的提示符Courier 或 Courier New 字体
方法Courier 或 Courier New 字体
对象Courier 或 Courier New 字体
路径名无突出显示
在上下文中定义的术语斜体
用户输入的文本Courier 或 Courier New 字体
“教程标题”引号
类型(例如 int 或 long)Courier 或 Courier New 字体
URL无突出显示
变量斜体。例如 “其中,myname 代表您的用户 ID。”
XML 标记或节Courier 或 Courier New 字体

步骤 4. 将文章或教程提交到 developerWorks

准备好内容之后,就可以将其发送给 developerWorks 编辑了。可以通过 E-mail 将文章或教程的 Word 或 Writer 文件(以及所有相关的图形或示例代码)发给编辑。有关如何为文章创建和提交图形的详细指导原则和技巧,请参阅 “developerWorks 投稿图片处理”。


下载

描述名字大小
用于 developerWorks 的 Microsoft Word 模板,V5.9author-package-word-V5.9-cn_20071115.zip291KB
用于 developerWorks 的 OpenOffice.org Writer 模板,V5.9author-package-writer-V5.9-cn_20071115.zip386KB

参考资料

学习

  • 您可以参考本文在 developerWorks 全球站点上的英文原文
  • 使用 developerWorks XML 模板写作”(developerWorks,2007 年 7 月):如果更愿意使用 XML 模板,在这个面向作者的可下载工具包中能够找到完整的操作指导和模板。
  • developerWorks 投稿图片处理”(developerWorks,2007 年 11 月):获得有关为文章或教程创建和提交插图的详细指导和提示。
  • developerWorks 投稿指南:在向 developerWorks 提交写作意向或稿件之前,请仔细阅读 developerWorks 投稿指南中的信息,这将帮助我们以最快的速度处理您的稿件。
  • developerWorks 征稿列表:了解每个 developerWorks 编辑的内容期望列表。

获得产品和技术

  • IBM 试用软件:用可直接从 developerWorks 下载的 IBM 试用软件构建您的下一个开发项目。

讨论

  • 内容提交表单:向 developerWorks 编辑提交文章或教程的要旨,并开始与 developerWorks 编辑对话。了解何种内容在 内容期望列表 中呼声最高。

条评论

developerWorks: 登录

标有星(*)号的字段是必填字段。


需要一个 IBM ID?
忘记 IBM ID?


忘记密码?
更改您的密码

单击提交则表示您同意developerWorks 的条款和条件。 查看条款和条件

 


在您首次登录 developerWorks 时,会为您创建一份个人概要。您的个人概要中的信息(您的姓名、国家/地区,以及公司名称)是公开显示的,而且会随着您发布的任何内容一起显示,除非您选择隐藏您的公司名称。您可以随时更新您的 IBM 帐户。

所有提交的信息确保安全。

选择您的昵称



当您初次登录到 developerWorks 时,将会为您创建一份概要信息,您需要指定一个昵称。您的昵称将和您在 developerWorks 发布的内容显示在一起。

昵称长度在 3 至 31 个字符之间。 您的昵称在 developerWorks 社区中必须是唯一的,并且出于隐私保护的原因,不能是您的电子邮件地址。

标有星(*)号的字段是必填字段。

(昵称长度在 3 至 31 个字符之间)

单击提交则表示您同意developerWorks 的条款和条件。 查看条款和条件.

 


所有提交的信息确保安全。


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=10
Zone=XML, Architecture, Java technology, Linux
ArticleID=269592
ArticleTitle=使用 developerWorks Word 和 Writer 模板写作
publish-date=11152007