使用 JavaScript 改进您的文档 我们最喜欢的开源资源
开源软件项目通常有非常多样化的用户群。 一些用户可能非常擅长使用该系统并且需要很少的文档。 对于这些高级用户，文档可能只需要是提醒和提示，并且可以包含更多技术信息，例如在 shell 中运行的命令。 但其他用户可能是初学者。 这些用户在设置系统和学习如何使用它方面需要更多帮助。
编写适合两个用户组的文档可能会让人望而生畏。 该网站的文档需要以某种方式平衡“详细的技术信息”与“提供更多的概述和指导”。 这是一个很难找到的平衡点。 如果您的文档不能同时满足这两个用户组，请考虑第三种选择——动态文档。
探索如何向网页添加一点 JavaScript，以便用户可以选择只显示他们想要查看的信息。
构建您的内容
您可以使用文档需要同时适合专家和新手用户的示例。 在最简单的情况下，您可以使用名为 AwesomeProject 的自制音乐播放器。
您可以使用 HTML 中的类功能编写一个简短的安装文档，为专家和新手提供说明。 例如，您可以使用以下方式定义专供专家使用的段落：
<p class="expert reader"> 这分配了专家类和读者类。 您可以使用以下方法为新手创建一组平行的说明：
<p class="novice reader"> 完整的 HTML 文件包括供新手读者和专家阅读的两个段落：
<!DOCTYPE html>
<html lang="en">
<head>
<title>How to install the software</title>
</head>
<body>
<h1>How to install the software</h1>
<p>Thanks for installing AwesomeProject! With AwesomeProject,
you can manage your music collection like a wizard.</p>
<p>But first, we need to install it:</p>
<p class="expert reader">You can install AwesomeProject from
source. Download the tar file, extract it, then run:
<code>./configure ; make ; make install</code></p>
<p class="novice reader">AwesomeProject is available in
most Linux distributions. Check your graphical package manager and search for AwesomeProject to install it.</p>
</body>
</html>这个示例 HTML 文档没有关联的样式表，因此在 Web 浏览器中查看它会显示两个段落：
图片来源：
（吉姆·霍尔，CC BY-SA 4.0）
我们可以对文档应用一些基本样式，以突出显示任何元素，无论是读者、专家还是新手。 为了使不同的文本类别更容易区分，让我们将读者类别设置为米白色背景色，专家级设置为深红色文本颜色，新手设置为深蓝色文本颜色：
<!DOCTYPE html>
<html lang="en">
<head>
<title>How to install the software</title>
<style>
.reader {
background-color: ghostwhite;
}
.expert {
color: darkred;
}
.novice {
color: darkblue;
}
</style>
</head>
<body>
<h1>How to install the software</h1>当您在 Web 浏览器中查看页面时，这些样式有助于突出这两个部分。 安装说明的两个段落都有灰白色背景颜色，因为它们都有阅读器类。 第一段使用深红色文本，由专家级定义。 第二个安装段为深蓝色文字，来自新手班：
图片来源：
（吉姆·霍尔，CC BY-SA 4.0）
我们最喜欢的关于开源 Git 备忘单的资源 高级 Linux 命令备忘单 开源替代品 免费在线课程：RHEL 技术概述 查看更多备忘单
添加 JavaScript 控件
应用这些类后，您可以添加一个简短的 JavaScript 函数，该函数仅显示一个内容块。 编写此函数的一种方法是首先设置 display:none 到具有阅读器类的所有元素。 这会隐藏内容，因此不会显示在页面上。 然后函数应该设置 display:block 到您要显示的类的每个元素：
<script>
function readerview(audience) {
var list, item;
// hide all class="reader"
list = document.getElementsByClassName("reader");
for (item = 0; item < list.length; item++) {
list[item].style.display = "none";
}
// show all class=audience
list = document.getElementsByClassName(audience);
for (item = 0; item < list.length; item++) {
list[item].style.display = "block";
}
}
</script>要在 HTML 文档中使用此 JavaScript，您可以将函数附加到按钮。 自从 readerview 函数将受众作为其参数，您可以使用要查看的受众类来调用该函数，无论是新手还是专家：
<!DOCTYPE html>
<html lang="en">
<head>
<title>How to install the software</title>
<style>
.reader {
background-color: ghostwhite;
}
.expert {
color: darkred;
}
.novice {
color: darkblue;
}
</style>
</head>
<body>
<script>
function readerview(audience) {
var list, item;
// hide all class="reader"
list = document.getElementsByClassName("reader");
for (item = 0; item < list.length; item++) {
list[item].style.display = "none";
}
// show all class=audience
list = document.getElementsByClassName(audience);
for (item = 0; item < list.length; item++) {
list[item].style.display = "block";
}
}
</script>
<h1>How to install the software</h1>
<nav>
<button onclick="readerview('novice')">view novice text</button>
<button onclick="readerview('expert')">view expert text</button>
</nav>
<p>Thanks for installing AwesomeProject! With AwesomeProject,
you can manage your music collection like a wizard.</p>
<p>But first, we need to install it:</p>
<p class="expert reader">You can install AwesomeProject from
source. Download the tar file, extract it, then run
<code>./configure ; make ; make install</code></p>
<p class="novice reader">AwesomeProject is available in
most Linux distributions. Check your graphical package
manager and search for AwesomeProject to install it.</p>
</body>
</html>有了这些控件，网页现在允许用户选择他们想要查看的文本：
图片来源：
（吉姆·霍尔，CC BY-SA 4.0）
单击任一按钮将仅显示用户想要阅读的文本。 例如，如果您单击“查看新手文本”按钮，那么您只会看到蓝色段落：
图片来源：
（吉姆·霍尔，CC BY-SA 4.0）
单击“查看专家文本”按钮隐藏新手文本并仅以红色显示专家文本：
图片来源：
（吉姆·霍尔，CC BY-SA 4.0）
将此扩展到您的文档
如果您的项目需要您为不同的受众编写多个操作文档，请考虑使用此方法发布一次并阅读两次。 为所有用户编写一个文档，让每个人都可以轻松找到和共享您项目的文档。 而且您不必维护仅在细节上有所不同的并行文档。
