如何编写易于访问的技术文档 - 最佳实践与示例

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

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

（本文视频讲解：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）

本文来自互联网用户投稿，该文观点仅代表作者本人，不代表本站立场。本站仅提供信息存储空间服务，不拥有所有权，不承担相关法律责任。如若转载，请注明出处：http://www.mzph.cn/news/818607.shtml

如若内容造成侵权/违法违规/事实不符，请联系多彩编程网进行投诉反馈email:809451989@qq.com，一经查实，立即删除！

相关文章

JS-30-async函数

JS-30-async函数

上一节说&#xff0c;JavaScript异步操作需要通过Promise实现&#xff0c;一个Promise对象在操作网络时是异步的&#xff0c;等到返回后再调用回调函数&#xff0c;执行正确就调用then()&#xff0c;执行错误就调用catch()。 虽然异步实现了&#xff0c;不会让用户感觉到页面“…
阅读更多...
07 SQL进阶 -- 集合运算 -- 表的加减法

07 SQL进阶 -- 集合运算 -- 表的加减法

1. 表的加减法 1.1 什么是集合运算 集合在数学领域表示“各种各样的事物的总和”, 在数据库领域表示记录的集合. 具体来说,表、视图和查询的执行结果都是记录的集合, 其中的元素为表或者查询结果中的每一行。 在标准 SQL 中, 分别对检索结果使用 UNION, INTERSECT, EXCEPT 来…
阅读更多...
【企业场景】设计模式重点解析

【企业场景】设计模式重点解析

设计模式 在平时的开发中&#xff0c;涉及到设计模式的有两块内容&#xff1a; 我们平时使用的框架&#xff08;比如spring、mybatis等&#xff09;我们自己开发业务使用的设计模式。 在平时的业务开发中&#xff0c;其实真正使用设计模式的场景并不多&#xff0c;虽然设计号…
阅读更多...
OpenHarmony实战开发-MpChart图表实现案例。

OpenHarmony实战开发-MpChart图表实现案例。

介绍 MpChart是一个包含各种类型图表的图表库&#xff0c;主要用于业务数据汇总&#xff0c;例如销售数据走势图&#xff0c;股价走势图等场景中使用&#xff0c;方便开发者快速实现图表UI。本示例主要介绍如何使用三方库MpChart实现柱状图UI效果。如堆叠数据类型显示&#xf…
阅读更多...
C#基础|数据类型、变量

C#基础|数据类型、变量

哈喽&#xff0c;你好啊&#xff0c;我是雷工&#xff01; 01 数据类型 数据类型是为了方便存储数据的&#xff0c;为了将数据按照不同的分类存储&#xff0c;所以引入数据类型。这个在PLC中已经很熟悉了。 数据类型的作用&#xff1a;就是为了更好地管理内存&#xff0c;为…
阅读更多...
嵌入式|蓝桥杯STM32G431（HAL库开发）——CT117E学习笔记13：RTC实时时钟

嵌入式|蓝桥杯STM32G431（HAL库开发）——CT117E学习笔记13：RTC实时时钟

系列文章目录 嵌入式|蓝桥杯STM32G431&#xff08;HAL库开发&#xff09;——CT117E学习笔记01&#xff1a;赛事介绍与硬件平台 嵌入式|蓝桥杯STM32G431&#xff08;HAL库开发&#xff09;——CT117E学习笔记02&#xff1a;开发环境安装 嵌入式|蓝桥杯STM32G431&#xff08;…
阅读更多...
基于Python长时间序列遥感数据处理及在全球变化、物候提取、植被变绿与固碳分析、生物量估算与趋势分析

基于Python长时间序列遥感数据处理及在全球变化、物候提取、植被变绿与固碳分析、生物量估算与趋势分析

原文链接&#xff1a;基于Python长时间序列遥感数据处理及在全球变化、物候提取、植被变绿与固碳分析、生物量估算与趋势分析https://mp.weixin.qq.com/s?__bizMzUzNTczMDMxMg&mid2247601336&idx4&sn143be5669da8ad336a455a4cca3d4b6a&chksmfa820d5fcdf584491…
阅读更多...
【机器学习】机器学习创建算法第6篇：线性回归,学习目标【附代码文档】

【机器学习】机器学习创建算法第6篇：线性回归,学习目标【附代码文档】

机器学习&#xff08;算法篇&#xff09;完整教程&#xff08;附代码资料&#xff09;主要内容讲述&#xff1a;机器学习算法课程定位、目标&#xff0c;K-近邻算法定位,目标,学习目标,1 什么是K-近邻算法,1 Scikit-learn工具介绍,2 K-近邻算法API。K-近邻算法&#xff0c;1.4 …
阅读更多...
【七 （1）指标体系建设-构建高效的故障管理指标体系】

【七 （1）指标体系建设-构建高效的故障管理指标体系】

目录 文章导航一、故障概述1、故障&#xff1a;2、故障管理&#xff1a; 二、指标体系概述1、指标2、指标体系 三、指标体系构建难点1、管理视角2、业务视角3、技术视角 四、指标体系构建原则1、与战略目标对齐2、综合和平衡3、数据可获得性4、可操作性5、具体和可衡量6、参与和…
阅读更多...
lua学习笔记20（lua中一些自带库的学习）

lua学习笔记20（lua中一些自带库的学习）

print("*****************************lua中一些自带库的学习*******************************") print("*************时间***************") --系统时间 print(os.time()) --自己传入参数得到时间 print(os.time({year2011,month4,day5})) --os.data(&qu…
阅读更多...
00 【哈工大_操作系统】Bochs 汇编级调试方法及指令

00 【哈工大_操作系统】Bochs 汇编级调试方法及指令

本文将介绍一下哈工大李治军老师《操作系统》课程在完成Lab时所使用到的 Bochs 调试工具的使用方法。这是一款汇编级调试工具&#xff0c;打开调试模式非常简单&#xff0c;只需在终端下输入如下指令&#xff1a; 1、bochs 调试基本指令大全 功能指令举例在某物理地址设置断点…
阅读更多...
Xxl-job执行器自动注册不上的问题

Xxl-job执行器自动注册不上的问题

今天新建的项目要部署xxl-job&#xff0c;之前部署过好多次&#xff0c;最近没怎么部署&#xff0c;生疏了。部署完之后&#xff0c;服务一直没有注册到执行器管理里面&#xff0c;找了半天也没找到原因&#xff0c;看数据库里的xxl_job_registry表也是一直有数据进来。 后来看…
阅读更多...
小白也能看懂的BEV感知（一）

小白也能看懂的BEV感知（一）

1. 引言 随着人工智能技术的不断发展&#xff0c;自动驾驶越来越多地出现在我们的视野中&#xff0c;智能化和电动化已经成为汽车行业的主旋律。无论是从研究的角度还是从工程的角度来看&#xff0c;它都像是一个巨大的宝藏&#xff0c;等待着我们去探索。本文将介绍这一技术的…
阅读更多...
从51到ARM裸机开发实验(009)LPC2138 中断实验

从51到ARM裸机开发实验(009)LPC2138 中断实验

一、场景设计 中断的概念在《从51到ARM裸机开发实验(007) AT89C51 中断实验》中已经介绍过&#xff0c;LPC2138的Keil工程创建在《从51到ARM裸机开发实验(005)LPC2138 GPIO实验》中已经介绍过。本次使用LPC2138来实现一个这样的场景&#xff1a;四个LED依次亮灭&#xff0c;时间…
阅读更多...
测试人必看，小程序常见问题

测试人必看，小程序常见问题

小程序是一种轻盈的存在&#xff0c;用户无需为了使用它而下载和安装。它依附于微信这个强大的平台&#xff0c;只需轻轻一扫或一搜&#xff0c;它便跃然屏上&#xff0c;随时服务。小程序为我们带来更多前所未有的惊喜和便利&#xff0c;以下分享关于小程序相关的热门问题。 …
阅读更多...
链表基础3——单链表的逆置

链表基础3——单链表的逆置

链表的定义 #include <stdio.h> #include <stdlib.h> typedef struct Node { int data; struct Node* next; } Node; Node* createNode(int data) { Node* newNode (Node*)malloc(sizeof(Node)); if (!newNode) { return NULL; } newNode->data …
阅读更多...
逆向IDA中Dword，数据提取

逆向IDA中Dword，数据提取

我们可以看见数据是这样的&#xff0c;第一个是1cc 但是我们shifte就是 这个因为他的数据太大了&#xff0c;导致高位跑后面去了 这个时候&#xff0c;我们右键——convert——dword 这样就可以提取到争取的数据了 比如第一个数据 0x1cc a0xcc b0x1 print(hex((b<<8…
阅读更多...
HarmonyOS开发实例：【事件的订阅和发布】

HarmonyOS开发实例：【事件的订阅和发布】

介绍 本示例主要展示了公共事件相关的功能&#xff0c;实现了一个检测用户部分行为的应用。具体而言实现了如下几点功能&#xff1a; 1.通过订阅系统公共事件&#xff0c;实现对用户操作行为&#xff08;亮灭屏、锁屏和解锁屏幕、断联网&#xff09;的监测&#xff1b; 2.通…
阅读更多...
vmware安装ubuntu-18.04系统

vmware安装ubuntu-18.04系统

一、软件下载 百度网盘&#xff1a; 链接&#xff1a;https://pan.baidu.com/s/1fK2kygRdSux1Sr1sOKOtJQ 提取码&#xff1a;twsb 二、安装ubuntu系统 1、把ubuntu-18.04的压缩包下载下来&#xff0c;并且解压 2、打开vmware软件&#xff0c;点击文件-打开 3、选择我们刚刚解…
阅读更多...
6. Django 深入模板

6. Django 深入模板

6. 深入模板 6.1 Django模板引擎 Django内置的模板引擎包含模板上下文(亦可称为模板变量), 标签和过滤器, 各个功能说明如下: ● 模板上下文是以变量的形式写入模板文件里面, 变量值由视图函数或视图类传递所得. ● 标签是对模板上下文进行控制输出, 比如模板上下文的判断和循…
阅读更多...
推荐文章
最新文章

Copyright @ 2022~2023