小团队如何搭建结构化内容开发环境

有不少小型文档团队想转结构化写作和发布，但是因为有限的IT技能和IT资源而受阻。本文为这样的小型文档团队而准备，描述怎样搭建一个环境，用于结构化内容的开发和发布。

 

- 1 -

目标

搭建一个结构化内容环境，具有以下功能：

1. 能够对内容进行版本管理；

2. 能够在团队成员之间进行协作；

3. 能够进行结构化内容创建和修改；

4. 能够将结构化内容发布成PDF/HTML等格式。

- 2 -

整体结构

系统由以下部分组成：

1. Git服务器

    用于内容的版本管理和团队之间协作。

2. 编辑器

    用于结构化内容开发和维护。

3. 发布工具

    用于结构化内容发布。

其中，Git服务器安装在服务器上。编辑器、Git客户端和发布工具安装在个人电脑上。 

- 3 -

环境搭建

3.1 Git服务器

Git是一个开源的分布式版本控制系统，可以有效、高速地处理从很小到非常大的项目版本管理，最初用于管理计算机代码。这里我们用它来管理结构化内容、图片、视频等。

如果内容需要保密，那么在公司内部获得一台服务器，在上边安装Git服务器比较合适，比如：Gitlab软件 - https://www.gitlab.com。在这台内部服务器上安装并配置Git服务器软件。

如果可以接受将内容放在云服务器上，我们可选择一个Git服务。提供Git服务的公司很多，这里以Gitee为例说明步骤。

1. 在浏览器中登录www.gitee.com，注册用户。

2. 创建仓库，用于保存结构化内容。

 

3. 邀请其他成员

邀请成员加入仓库，一起开发文档。

在仓库界面，选择：管理 -> 仓库成员 -> 所有。然后点：添加仓库成员 -> 邀请用户。

3.2 Git客户端

Git客户端用于从个人电脑上连接Git服务器，将内容拉到个人电脑上进行编辑，然后将更新好的内容推送到Git服务器上。

可用的Git客户端很多，我们这里使用的是Github Desktop。 

1. 从以下网址下载Github Desktop软件。

https://desktop.github.com/

2. 双击下载的GithubDesktopSetup-x64.exe，进行安装。

3. 运行Github desktop，拉取项目内容。

上图的Repository URL填写Gitee上创建的仓库URL，从下图处获取：

内容放在本地磁盘的C:\dev\dyson目录，目前目录中无内容。

3.3 编辑器

全面支持XML编辑的编辑器有Oxygen XML Editor, Arbortext Editor, XMetaL, XMLSpy, XMLMind等。VS Code在纯文本编辑的基础上提供XML编辑的支持。Oxygen在国内应用广泛，本文以它为例进行说明。

1. 登录Oxygen网站下载Oxygen XML Editor

https://www.oxygenxml.com/xml_editor.html

在网站购买或者获得测试版授权。 

2. 双击下载的oxygen-64bit-openjdk.exe，进行安装。

3. 运行Oxygen XML Editor并创建内容。

通过Oxygen XML Editor创建ditamap和topic。文件目录结构如下：

4. 将内容推送到Git服务器

打开Github Desktop，填写说明，点下方commit to master按钮提交内容。然后，点上方的Push Origin，将内容推送到Git服务器。

3.4 发布工具

内容发布工具将结构化内容发布成PDF、HTML、MS Word等格式。对于DITA格式的结构化内容，业界使用得最多的发布工具是DITA-OT（DITA Open Toolkit - https://www.dita-ot.org/）。

Oxygen XML Editor集成了DITA-OT并提供图形界面。所以无需额外安装。

下边是如何在Oxygen编辑器中将ditamap发布成PDF：

1. 在Oxygen中打开ditamap文件。

2. 发布PDF。

- 4 -

总结

本文使用Gitee和Oxygen，为小型文档团队搭建结构化文档开发环境。系统包含了版本管理、协作、编辑和发布的基本功能。为小型团队进行结构化内容开发扫清障碍。