ClickHelp as a DITA Alternative

单击“帮助”按钮作为达尔文信息分类体系结构的备选方案

2021-01-13 15:00 clickhelp

本文共2084个字,阅读需21分钟

阅读模式 切换至中文

What Is DITA? DITA is short for The Darwin Information Typing Architecture. It comprises the principles of specialization and inheritance that are much like the Darwinian theory. “Information typing” means the classification of information into topics, not “typing” as in keyboarding :) “Architecture” is a hierarchy of elements or adaptable set of structures. It provides vertical headroom (new applications) and lateral extension (specialization into new types) for information. “DITA is an XML standard for authoring, generating, and providing technical information.” The idea of creating such a data model belongs to IBM, which needed more effective reuse of content in products’ documentation. So the technical publications department presented DITA in 2001 for internal use. In 2004 DITA was donated to the OASIS standards organization. The latest version was released in 2016, it’s called DITA V1.3 Errata 01. DITA consists of a set of design principles that help to create and manage content separately from formatting. If you want to understand how it works, you must understand how DITA uses topics, maps, and output formats. You create your content in DITA topics, apply DITA maps to define which topics move into which deliverables, then handle those maps to DITA output formats to produce your final deliverables. What Is a DITA Topic? A topic is the basic content unit of DITA. It is understood separately and used in different contexts. A topic should be brief to distinguish a single subject or answer a single question; at the same time, it must make sense and be written as an independent item. It has a fixed structure, which helps topics be consistent even when written by different authors. DITA 1.0 and 1.1 provides three basic topic types: concept topics for overview and high-level explanatory information task topics for information about performing specific tasks reference topics for detailed information DITA 1.2 includes additional topic types (specialized for learning plans, overviews, summaries, and assessments). Confused already? Yes, it’s not so simple. And DITA introduces a lot of items that should be well-understood for the efficient application of this approach in action. Let’s continue to introspect in other elements to understand what issues are addressed with the help of DITA for the technical documentation creation process. What Is a DITA Map? A map is a list of indications to a set of some particular topics. It determines topics to incorporate into the deliverables. The map also establishes the order and hierarchy of the topics and ensures browsing, such as TOC and cross-topic links in the final deliverable. Maps can be created at any time, even before the topics’ development. Additionally, maps can create multiple deliverables from a single set of topics. Typically, more than half of topics are used in multiple maps. You should remember not to create a dependency between topics, they should be context-neutral. Because in case of some changes in such dependent topics, your reader may go on the wrong path. You can also use a single map for multiple deliverables. Maps can point not only to topics but also to other maps. Using maps gives you flexibility but can significantly complicate the understanding of the process. In cases you need only two or three output variants with the set of topics that are 90% concurrent, the creation of separate maps for each output can bring in extra overhead. What Is an Output Format in DITA? Output formats allow producing various deliverables suitable for different purposes (posting to the web, printing, etc.) from a content. By default, the DITA-OT provides output formats for: XHTML Compressed HTML Help (.chm) PDF Eclipse Help JavaHelp Rich Text Format (RTF) etc. Also, you can develop your own output format. It can be modified to match the templates you developed in the tools you used before, for example, Microsoft Word. But it’s not an easy task to do. Output formats can control the arrangement of your deliverables since DITA uses semantic tagging rather than format tagging. Semantic tagging helps to indicate the nature of the content. Each output format has the corresponding settings for the target file type. It means that you define how and in what form each element must be included in the output, based on the type of such element: topic, main content, link element, numbered list, etc. The Pros and Cons of DITA The most evident advantages of using DITA are the following: Content reuse. The same introductions, glossaries, and “how to use” sorts of wording can be used in multiple documents. Multi-format output. Deliver content in multiple formats and reconstruct topics to make a customized output. You combine the information in a single content as needed and output it into various formats. Single-source your content. Aim information for a certain user type and context. What goes into a user manual will differ from the content of a product overview or a datasheet. So, basically, you create some topic just once, and DITA helps you use it in multiple deliverables for different purposes. And if you have multiple outputs with overlapping content, it is convenient to use DITA. However, every story has two sides. And here’s the other side of DITA’s: Integration: it’s not easy to integrate DITA into existing web frameworks. Such frameworks have templates with good display across your devices. Without these, you spend a lot of time on your hands. JavaScript libraries are also a challenge to integrate with DITA. To get it work, you’ll probably have to fit the ax in the helve because the classes and IDs are critical for Java plugins, and, again, you’re spending precious time to solve the issue. If you have some non-DITA content integration of such content with DITA will give you an additional quandary. The “Information typing” aspect is hard to understand. You’ll be figuring out how to structure your content, and complex elements are just a hindrance here. Combining a lot of small topics don’t work so well. Writing in XML is a back-breaker. You must know the order of allowed elements and not just which of them to use. This language is too lengthy and not human friendly, it was created for computers first of all. Customization. If you need to customize your output, DITA is not much of a helper here. To transform XML elements into HTML, you should first customize the XSL-FO (eXtensible Stylesheet Language Formatting Objects) stylesheet. Support. DITA doesn’t support Microsoft PowerPoint, and PDF modification is tricky. The three basic topic types available in DITA work well with tech docs but not always fit for educational content. You must decide whether you really need such a standard in your work. If you do not update your documents regularly or reuse the same content in various combinations, maybe you can do just fine without DITA. The next issue is the price: the shift to DITA demands a significant infusion of resources - CMSs can be expensive to implement with DITA. It requires experts to manage the transition. You'll probably spend a lot of time developing your information architecture rather than writing the docs for your company. In addition to the reliable CMS itself, that you need to buy. This is about an investment of tens of thousands of dollars and 12-18 months of hard work, in some cases, even more. Moreover, staffing is quite a challenge. Not so many people know DITA, that’s why their salaries are high. If put together all these points, DITA may prove to be not so cost-effective. Usually, it’s a bundle for small and medium businesses. Another problem is acceptance: documentation managers must decide on what to rewrite, reuse, convert, and neglect. It’s not an easy task if you have several managers: each has a certain set of documents that they consider important, so the settling of this issue may raise a conflict, which is time-consuming and may delay the transition considerably. One more important point is training since DITA is not so simple as one might think. It takes time and money. Some writers like to keep with the traditions and do not like to leave their comfort zone, so they protest against the process. And a technical writer must distract a lot to understand DITA, it’s not as intuitive as they put it. ClickHelp as the Right Alternative to DITA Now, when DITA is not just a word for you, and you understand the core concepts, let me tell you about your other option. If you need to make a professional approach to user documentation, you can use ClickHelp. This online documentation tool addresses the same issues much easier. ClickHelp is a cloud-based tool with no need of installing anything. You can sign up and get your own ready-made portal in the vendor’s cloud. It protects access for authors with SSO, or you can use simple login and password. ClickHelp works in a web browser from any place in the world. You can easily run a review process for your content, publish, and update your user guides quickly. Let’s have a look at professional technical writing functions that ClickHelp offers and how they cover DITA use cases: Content reuse. ClickHelp helps to make content reuse simple and clear. Snippets and variables are essential for it. You insert a snippet, and it becomes a part of your topic for readers, but for authors, it remains a special entity that can be edited in one place while updated throughout the documents it was used. This way, you save a lot of time maintaining reused content. Multi-format output. You can easily maintain your documentation online and then export it to any format you need. Single-sourcing. Single-sourcing can make any documentation authoring process more efficient. With ClickHelp, you don’t need to make up DITA maps and write XML, you just visually choose what elements should be placed into a certain output with the help of Output Tags. Content styling. While editing topic contents, you can use various styles for the text content - make it bold/underline/italic, change the font size and color, etc. It’s important to stay consistent with such element styling as tables, lists, etc., so your docs look professional. For better consistency, you can manage the styles of those elements in a shared CSS style file that is used in all your articles. A visual editor doesn’t require your understanding of XML. But in case you need to have low-level control over HTML code it allows you to get access to HTML source. Teamwork. When you create a project online as a team, it’s crucial to work in a coordinated manner. ClickHelp comprises a lot of possibilities for Teamwork. All of your team can work on one portal despite their physical location. They can use workflow to assign topics for each other for collective work. To get input from SMEs or let others proofread your content, they can use a review workflow. It’s an integrated teamwork environment, not just an author tool. Publishing and delivery. When your content is ready, you can easily publish docs for readers on your portal. Some of the documents can be password-protected, and some left public. You can freely revise your documents and update one or several topics at once. It can save you a good deal of time since you don’t need to ask a webmaster or IT Department to upload your new files to the site and wait for several days while they have time to do it. As a technical writer, you can manage your documentation site in an efficient manner to save time and effort. “With ClickHelp, you get a ready-made documentation site with the teamwork functions and documentation hosting.” Conclusion Implementation of such standards as DITA is a long-range project that consumes time, money, and human resources. And grasping at new trends because everyone is following them is not the right way to go. Instead, maybe you need to take time, look around, and find another alternative for your documents to be structured. ClickHelp might be just what fits you best - content reuse and dynamic output are paired with the ease of use for better documentation delivery. Give it a try, and you will see that DITA is not the only approach to professional documentation writing. Good luck with your technical writing! ClickHelp Team Author, host and deliver documentation across platforms and devices
达尔文信息分类体系结构是什么? DITA是达尔文信息类型体系结构的简称。它由专门化和继承性原则组成,上述两原则与达尔文理论非常相似。“信息键入”代表将信息分类作为主题,而不是键盘中的“键入”键:) “体系架构”为要素的层次架构或可修改的架构合集。该合集为信息提供了纵向净空即新应用程)和横向扩展即专门化到新类型。 达尔文信息类型体系结构是一种XML标准,用于写作,生成和提供技术信息。 创建这此数据模型的主意来自IBM,IBM需要以更有效地方式重复使用产品文档中的内容。因此,在2001年,技术出版物部门提出了达尔文信息类型体系结构以供内部使用。2004年,达尔文信息类型体系结构捐赠给了OASIS标准组织。达尔文信息类型体系结构的最新版本发布于2016年,名为DITA V1.3勘误表01。 达尔文信息类型体系结构由一组助创建和管理内容与格式化分开的设计原则构成,。如果你想探寻其工作原理,了解是达尔文信息类型体系结构如何使用主题,映射和输出格式的是必要的。在达尔文信息类型体系结构主题中创建内容时,应用达尔文信息类型体系结构映射进而定义哪些主题能移到交付品中,然后处理这些映射达尔文信息类型体系结构为输出格式,以生产最终的交付品。 达尔文信息类型体系结构的主题是什么? 达尔文信息类型体系结构的基本内容单元是其一个主题。它是分开理解的并在不同的上下文中得以使用。主题应该简短,从而达到区分单一主题或回答单一问题的目的;与此同时,主题一定要有意义,并作为一个独立的条目来撰写。它有一个固定的结构,这有助于让即使是由不同的作者编写的主题保持一致。达尔文信息类型体系结构1.0和1.1提供了三种基本主题类型: 概念主题:为综述和解释高级别信息 任务主题:为执行有关特定任务信息 参考主题:用于有关详细信息 达尔文信息类型体系结构1.2涵盖其他类型的主题(专门用于学习计划,概论,摘要和评估等目的)。 (说到这里)大家已经混乱了吗?正是如此,达尔文信息类型体系结构较为复杂。并且达尔文信息类型体系结构引入了许多项目,为了在实践中,有效地应用这些项目,我们应该充分了解他们。让我们继续反思其他元素,以了解在达尔文信息类型体系结构的帮助下,在技术文档创建过程中,我们能解决了哪些问题。 达尔文信息类型体系结构地图是什么? 达尔文信息类型体系结构地图为一组特定主题的指示列表。该主题决定着需并入到可交付成果的主题。达尔文信息类型体系结构地图还构筑主题的顺序和层次结构,从而确保浏览任务的完成,如存在最终交付品中的TOC和跨主题链接。在任何时候,我们都可以创建地图,即使是在主题开发之前也能创建地图。此外,该地图能够可以创建多个可交付结果,仅仅利用一组主题。通常情况下,在多个地图中我们会使用超过一半的主题。需要记住的是不要在主题之间创建依赖关系,它们之间并不存在上下文之间的联系。原因在于这类存在依赖关系的主题一旦发生些变化,受众存在着误入歧途的可能。也可以将单一的地图用于多个可交付成果。此类地图不单单可以指向主题,还能指向其他的地图。使用此类给予你极大的灵活性,但有明显使理解过程复杂化的可能。如果您只需要两个或三个输出变量,并且主题集是90%并发的,这种情况下每个输出创建单独的地图会产生额外的开销。 什么是达尔文信息类型体系结构中的输出格式? 输出格式允许从一个内容生成各种可交付结果,这些结果适合于不同目的(张贴到web,打印等)。默认情况下,DITA-OT提供以下输出格式: XHTML格式 压缩的HTML Help 格式(。chm) PDF格式 Eclipse Help格式 JavaHelp 格式 RTF格式 等等。 初次此外,您还可以开发属于你自己的输出格式。为了匹配您在以前使用的工具(例如Microsoft Word)中开发的模板,你也可以对其进行修改,。但这并非易事。 因为DITA使用语义标记而不是格式标记,所以输出格式可以控制交付结果的排列。语义标记有助于指出内容的性质。对于每种输出格式来说,都有其对应的目标文件类型设置。这意味着您怎样以及如何定义每个元素必须必须包含在输出中,基于这样的元素的类型:主题,主要内容,链接元素,编号列表等。 达尔文信息类型体系结构的优缺点 达尔文信息类型体系结构最显著的优点如下: 内容重复使用。可以在多个文档中使用相同的介绍,术语表和“如何使用”的措辞。 多格式输出。传递内容可以使用多种格式,为了制作自定义输出可重构主题。您可以根据需要在单个内容中组合信息,并将其输出为各种格式。 针对特定用户类型和上下文的目标信息,使你的内容来自单一来源。使用户手册的内容与产品概述或数据手册有着不同的内容。 因此,基本上,您只需创建一次主题,达尔文信息类型体系结构帮助您将此主题用于不同目的的多个交付品中。而且如果您有多个内容重叠的输出,那么使用达尔文信息类型体系结构是很方便的。 然而,每个故事都有两面性。达尔文信息类型体系结构的另一面为: 合集:将达尔文信息类型体系结构集成到现有的web框架中并非易事。这样的框架在您的设备上具有显示良好的模板。如果没有这些,你就会在手上花很多时间。对于达尔文信息类型体系结构集成来说,JavaScript库与也是一个挑战。为使其工作,您可能必须把斧头插在刀架上,因为类和ID对于Java插件来说是至关重要的,而且,您还要花费宝贵的时间来解决这个问题。如果您有一些非达尔文信息类型体系结构内容,那么将这些内容与达尔文信息类型体系结构集成将给您带来额外的困惑。 很难理解的一个方面在于“信息键入”。如何构建内容需要弄清楚,这里的一个障碍是复杂的元素。把一大堆小题目结合起来,效果不是那么好。 后退程序需用XML格式来编写。必须了解的是所允许的元素的顺序,而不仅仅是要使用哪一个元素。这种语言太冗长,对人类不友好,它的首要目的是为计算机创造的。 定制。如果您需要自定义输出。此处达尔文信息类型体系结构并不是好的助手。要将XML元素转换为HTML格式,首先应该自定义XSL-FO(可扩展样式表语言格式化对象)样式表。 支援。达尔文信息类型体系结构不支持Microsoft PowerPoint格式,PDF格式修改起来也并非易事。达尔文信息类型体系结构中的三种基本主题类型可以很好地用于技术文档,但并不总是适合教育内容。 必须决定的是,工作中你是否真的需要遵循这一标准。如果您不定期更新文档或以各种组合重复使用相同内容,也许您可以在没有达尔文信息类型体系结构的情况下做得很好。 下一个是价格问题:转向使用达尔文信息类型体系结构,我们需要注入大量的资源--并且它可能会很昂贵对于使用达尔文信息类型体系结构实现CMSs。上述要求需要专家出场,管理过渡。可能会花费大量时间开发信息架构,而不是为公司编写文档。除了可靠的CMS本身,其他都需要购买。它涉及数万美元的投资以及12-18个月的努力,在某些情况下,甚至更多。而且,人员配备也是一个相当大的挑战。没有那么多人知道达尔文信息类型体系结构,他们薪水高的原因便在于此。如果把所有这些点放在一起,达尔文信息类型体系结构可能被证明为不是那么具有成本效益。通常,这是一个捆绑中小企业。 另一个问是接受性问题:文档管理人员必须决定重重复使用什么,,转换什么,忽略什么。如果你有几个经理,这可不是一件容易的事:每个经理都有一套他们认为很重要的文件,因此解决这个问题可能会引起冲突,这会耗费时间,并可能会大大推迟过渡。 更为重要的一点是训练问题,因为达尔文信息类型体系结构并不像人们想象的那么简单。时间和金钱尤为需要。有些作家喜欢遵循传统,不喜欢离开自己的舒适区,基于以上原因,因此他们对这种做法表示抗议。而一个技术作家必须花很多精力来理解达尔文信息类型体系结构,它并不像他们说的那么直观。 ClickHelp为达尔文信息类型体系结构的正确替代品 当今,当达尔文信息类型体系结构对您来说不仅仅是一个单词,而您了解其核心概念的时候,我会告诉你另一个选择。如果需要对用户文档进行专业处理,可以使用ClickHelp。对于解决同样的问题,这个软件更容易处理。 ClickHelp是一个基于云的工具,你不需要安装任何东西。您可以在供应商的云用户中获得自己的现成门户通过注册的方式。它保护作者的访问通过SSO,或者您可以使用简单的登录和密码。ClickHelp可以在世界上任何地方的web浏览器中工作。您可以轻松地对内容运行审阅过程,发布和快速更新用户指南。 让我们来看看ClickHelp提供的专业技术编写功能,以及它们如何覆盖当达尔文信息类型体系结构用例: 内容重复使用。ClickHelp使重复使用的内容变得简单明了大有裨益。对它来说是必不可少的要素在于片段和变量。插入一个片段,对于读者来说,它就成为主题的一部分,但是对于作者来说,它仍然是一个特殊的实体,可以在一个地方编辑,同时在使用它的整个文档中更新。这样,您就可以节省大量维护重用内容的时间。 多格式输出。您可以以一个轻松的方式在线维护您的文档,然后将其导出为您所需要的任何格式。 单一来源。单一来源作用在于可使任何文档在创作过程更未有效。使用ClickHelp,您不需要利用当达尔文信息类型体系结构地图和编写XML格式,您只需借助输出标记可视化地选择应该将哪些元素放置到某个输出中。 内容样式。在编辑主题内容时,可以使用这个样式来编辑文本内容--将其变为粗体/下划线/斜体,更改字体大小和颜色等。至关重要的点在于使其与表格,列表等元素样式保持一致,如此一样您的文档看起来就很专业了。为了达到高水平一致性的目的,您可以在所有文章中使用的共享CSS样式文件中管理这些元素的样式。可视化编辑器不需要您理解XML格式。但如果您需要对HTML代码进行低级控制,它允许您访问HTML源代码。 团队合作。当你以一个团队的形式在线创建一个项目时,至关重要的点在于以一种协调的方式工作。ClickHelp包含了许多团队合作的可能性。您的所有团队都可以在一个门户上工作,不管他们的物理位置如何。他们可以使用工作流为彼此分配主题进行集体工作。要从中小企业获得输入或让其他人校对您的内容,他们可以使用审阅工作流。它是一个集成的团队工作环境,而不仅仅是一个作者工具。 发布和交付。在相关内容准备就绪后,您可以轻松地在门户上为读者发布文档。有些文档可以有密码保护,有些则是公开的。您可以自由地修改您的文档,并一次性更新一个或几个主题。因为您不需要要求网站管理员或It部门上传您的新文件到站点和等待几天,而他们有时间做这件事,由此可节省大量时间。作为一名技术作家,您可以以高效的方式管理您的文档站点,从而节省时间和精力。 “使用ClickHelp,您可以获得一个现成文档站点,它具有具有团队工作功能和文档托管功能。” 结论 对达尔文信息类型体系结构来说,实现这一标准是一个长期的项目,需要花费时间,金钱和人力资源。因为每个人都在追随新趋势,所以抓住新趋势并不是正确的做法。相反,也许您需要花点时间,四处看看,并为您的文档结构化找到另一个替代方案。ClickHelp可能是最适合您的--内容重用和动态输出与易于使用相结合,从而更好地交付文档。试一试,您会发现达尔文信息类型体系结构并不是编写专业文档的唯一方法。 希望你在技术写作过程中农好运! 单击帮助小组 以跨平台和设备的方式编写,托管和船体文档

以上中文文本为机器翻译,存在不同程度偏差和错误,请理解并参考英文原文阅读。

阅读原文