如何编写易于访问的技术文档

当你为项目或工具编写技术文档时，你会希望它易于访问。这意味着它将为全球网络上的多样化受众提供服务并可用。

网络无障碍旨在使任何人都能访问网络内容。设计师、开发人员和撰写人员有共同的无障碍最佳实践。本文将涵盖一些创建技术内容的最佳实践。

（本文视频讲解：java567.com）

什么是网络无障碍？

网络无障碍是使任何人都能够消费或创建网络内容的实践，无论他们可能面临的健康、经济、地理或语言挑战是什么。

为什么网络无障碍很重要？

在你的项目中应用网络无障碍最佳实践有许多原因。

首先，它将帮助你触及更广泛的受众。当一个可能具有不同能力的人在网络上遇到一些数据 - 比如在你的网站上 - 他们会想要了解更多或使用这些数据。但如果他们无法访问，你将不会感到满意或获得良好的体验。

想象一下有多少人由于在制定产品、网站或工具的决策时没有考虑到他们而无法利用网络。

无障碍的另一个重要方面是它提高了你品牌的质量。通过在你的工作中实施无障碍功能，让人们知道你是一个注重无障碍的人或公司，这表明你希望你的信息对每个人都可用。它还显示了你在工艺上的多才多艺以及你适应时代和趋势变化的能力。

作为个人，应用无障碍最佳实践也会使你受益。对于具有出色无障碍技能的开发人员和设计师，可能会有就业机会。

良好的无障碍实践也意味着良好的SEO实践，这可能会使你的工作更具可见性。

最后，在世界某些国家，法律规定了无障碍要求，并且某些国家已实施了网络无障碍策略。如果你在你的网站和应用中忽视了无障碍功能，可能会带来法律后果。

软件工程师在使网络无障碍方面发挥着关键作用。但是在撰写文档时，技术撰写人员也有改善网络无障碍的责任。

技术撰写人员帮助撰写各种类型的内容，如用户指南、教程、API参考、代码文档等。

现在，让我们来看看在技术写作中实施网络无障碍的一些最佳实践。这些策略将有助于改进你的文档，并使其对每个人更加友好和易于访问。

使用清晰的标题和段落

在编写内容时，你应该确保使用标题 - 以及适当的标题层次结构（H1用于页面/文章的标题，H2用于主要标题，H3用于副标题，依此类推）。

此外，请确保将内容分成段落，以便阅读和理解更容易。

当你介绍一个新主题时，使用标题来突出显示。当你在该部分讨论更小的主题时，请使用副标题提醒读者。

标题对于帮助屏幕阅读器理解页面的内容以及如何通过页面进行导航非常重要。因此，请使用标题以便以逻辑方式引导读者浏览文本。

你可以使用井号在Markdown中表示标题。以下是按层次顺序排列的标题示例。

# 使用H1作为页面标题## 使用H2作为主要标题
这个标题是主要内容部分的主要标题。### 使用H3作为副标题
这个标题是更深入探讨主要部分中的一个点的副标题。

使你的内容清晰简洁

总的来说，尽量保持文档中的句子较短。这样可以使它们更容易阅读和理解（对于所有人都是如此）。如果需要，你也可以使用图像或视频提供更多细节。

确保在首次使用任何缩略词时给出完整的含义。此外，始终使用简单的句子，尽量不要使用含糊不清的词语。

下面是一个过于复杂、长句且词汇难度较高的示例：

基于区块链结构的Web3是透明的、安全的、不可改变的和去中心化的，它需要人工智能的过程，它会读取数据、处理和存储信息。

这个版本更好：

Web3建立在区块链透明、安全、不可更改和去中心化的结构之上。它利用人工智能过程来读取、处理和存储信息。

你的内容应包含你要传达的主要观点，消除所有形式的模棱两可。

使用信息丰富的链接文本

你所有的内联链接都应使用清晰、详细和描述性的文本。你可以描述链接的目的或者公司的名称，比如品牌。

链接对于提高页面的排名非常重要。使用“点击这里”或“”之类的链接并不是很有帮助，因为它们并不告诉读者在该链接中会找到什么。

例如，如果我想将W3C（万维网联盟）的无障碍教程链接到本文，我可以使用以下格式：查看W3C为内容撰写人员提供的资源。

为媒体内容添加alt文本和标题

图片

在alt文本属性中添加描述性文本可以让屏幕阅读器读出与图像相关联的alt文本。alt文本还有助于爬行页面的搜索引擎机器知道如何对该内容进行分类。

在添加alt文本时，描述图像的目的而不是图像本身。例如，假设你在关于容器化的部分使用了显示一些运输集装箱的图像。

在这里插入图片描述

在运动中的船上的各种集装箱，用以说明数字集装箱的包装结构和流程。

与其编写像“在运动中的船上的各种集装箱”这样的alt文本，你可以编写“在运动中的船上的各种集装箱，用以说明数字集装箱的包装结构和流程。”

尽管alt文本充当图像的替代品，但标题提供了有关图像的更多细节。你可以使用HTML插入图像标题。Markdown不支持图像标题，但是Markdown文档站点通常有解决方法（例如，通过插件 - ReadTheDocs、MkDocs - 或通过自定义组件插入HTML - Docusaurus）。

举例来说，我将展示如何在Docusaurus中添加图像标题。

在Docusaurus .md文件中添加图像标题的方法：

在src文件夹中创建一个名为components的文件夹。
创建一个名为figure.jsx的文件。
将以下代码添加到其中：

import React from "react"; 
import useBaseUrl from "@docusaurus/useBaseUrl"; 
export default function Figure({ src, caption }) {return ( <figure> <img src={useBaseUrl(src)} alt={caption} /> <figcaption>{`图: ${caption}`}</figcaption> </figure> ); 
}

转到包含图像的.md文件并导入代码。

import Figure from '@site/src/components/figure'; 
import figure1 from 'path-to-image';

将其添加到文件中。

<Figure caption="这是图像的标题" alt="这是alt文本" src={figure1} />

图像现在将显示带有标题。

在这里插入图片描述
图像标题的屏幕截图示例

视频

要为视频添加标题，HTML是一个很好的选择。但如果你使用markdown，你可以使用<iframe>标签嵌入来自YouTube和Vimeo的视频。这些应用程序提供内置的标题支持，因此你可以在添加嵌入代码之前启用标题。

你还可以安装第三方插件来实现这个目的。

另一个提示是：避免在视频中闪烁内容，因为这可能会引发癫痫发作。如果你的视频有闪烁的明亮颜色，请确保其在一秒内不超过两次。

为音频和视频添加文字稿

向音频和视频内容添加文字稿是一个好主意。并不是每个人都想要观看或听取内容。但他们可能会好奇知道内容是什么。

通过添加文字稿，你使任何人都能更轻松地浏览内容并获取他们所需的信息。

音频的文字稿

对于音频内容，你可以使用HTML插入文字稿。以下是一个示例：

<audio controls muted><!--总是将你的音频设置为静音--> <source src="ringtone.mp3" type="audio/mpeg"></source> 
</audio> 
<code> <p>这是文本的转录</p> 00:03 = 我今天要很有成效<br><br> 00:05 = 我今天要很有成效<br><br> 00:08 = 我今天要很有成效<br><br> 00:10 = 我今天需要很有成效<br><br> 00:11 = 我今天必须很有成效<br><br> 00:13 = 我今天应该很有成效<br><br> 00:16 = 我今天要很有成效<br><br> 00:18 = 我今天应该很有成效<br><br> 00:21 = 我今天必须很有成效<br><br> 00:23 = 生产力对我很重要 <br><br> 
</code>

对于像Docusaurus这样的Markdown文档站点，你可以创建一个自定义组件。

在你的src/components文件夹中，创建一个名为transcript.jsx的文件。
插入以下代码：

import React, { useState } from 'react'; 
export default function Transcript({ }) { const [showTranscript, setShowTranscript] = useState(false); const toggleTranscript = () => { setShowTranscript(!showTranscript); }; return ( <div> <a href="#" onClick={toggleTranscript}> { showTranscript ? '隐藏文本稿' : '查看文本稿'} </a> {showTranscript && ( <div id="transcriptText"> (插入你的文字稿文本) </div> )} </div> ); 
}

转到你的markdown文件并导入它。

import Transcript from '@site/src/components/transcript'; <Transcript />

在这里插入图片描述
音频文字稿输出的屏幕截图

注意： 我对代码进行了一些调整，使文本稿的显示是可选的。如果希望页面加载时显示文字稿，可以进行编辑。

视频的文字稿

对于视频，YouTube是一个很好的选择。它为您的视频提供了内置的文字稿。因此，您可以随时在文档中嵌入YouTube视频。

文字稿在主要详情之后的视频描述中。当您单击“显示文字稿”按钮时，文字稿将显示时间戳。

添加代码片段并使用颜色对比技术

如何添加代码片段

使用代码块来解释代码而不是图像。你还可以使用代码片段来展示代码的输出。除非必须添加图像，否则应该使用代码片段。

例如，

index.html
<!DOCTYPE html> 
<html> <head> <meta http-equiv="content-type" content="text/html; charset=utf-8" /> <title>一个计算器应用程序</title> <link rel="stylesheet" href="styles.css"/> </head> <body> </body> 
</html>

这将使屏幕阅读器能够阅读代码，而屏幕阅读器无法读取屏幕截图。

在这里插入图片描述
上传上述代码的屏幕截图

颜色对比技术

颜色对比技术意味着使用相反或强烈对比的颜色。

例如，使用黑色文字在白色背景上具有高对比度，而使用浅棕色文字在棕色背景上则没有。

在组合颜色时，你可以使用可访问的颜色调色板，如Color Safe。

在这里插入图片描述
从Color Safe获取的在绿色背景上使用淡白色的颜色

添加翻译选项

有些文档站点提供翻译选项，你可以在多种语言中构建你的文档，像Jekyll这样的网站。以下是一个示例。

Docusaurus也是另一个提供使用Crowdin或Git进行多语言选项的文档站点。

按照此指南设置Docusaurus的Git翻译和本地化。
按照此指南设置Docusaurus的Crowdin翻译和本地化。‌

使用无障碍测试工具

有些工具可以用来检查文档中的无障碍错误。一些示例是WAVE（Web无障碍评估工具）和AXE（无障碍引擎）。

此外，你可以获取NVDA（非视觉桌面访问）屏幕阅读器来测试你的内容。这款软件会告诉你使用屏幕阅读器的用户如何感知你文档的内容。‌

设置改进或建议框

最后，可能无法满足每个用户的需求。因此，你可以添加一个建议或改进框，允许用户发送关于如何进一步改进内容的反馈。直接从用户那里听到反馈可以帮助你了解如何最好地使文档对他们无障碍。

要添加改进框，你可以使用一个存储用户输入的外部表单链接，或者你可以在文档中设置建议框。

如何在Docusaurus中添加外部表单链接

你需要创建一个自定义组件。

进入src/components文件夹并创建一个名为feedback.jsx的文件。
添加以下代码：

import React from 'react'; export default function FeedbackButton({ href }) {return ( <a href={href} target="_blank" rel="noopener noreferrer" > 给予反馈 </a> ); 
};

在你的markdown文件中导入它：

import FeedbackButton from '@site/src/components/feedbackbutton';

插入链接：

<FeedbackButton href="https://forms.google.com" />

当你在文档中运行它时，它应该展示一个指向Google表单的链接。Google Forms是一个示例，你可以添加链接到你公司的网站或服务器。这是它的样子：

在这里插入图片描述
一个用于文档建议的反馈链接

总结

要遵循和实施这些无障碍最佳实践，你可以考虑创建或使用一个已经制定好的样式指南。这可以帮助你持续地实施这些实践，并使你和团队中的其他技术撰写人员更容易地做到这一点。

（本文视频讲解：java567.com）