如何写一个教程

前言

随着社区人数的增加,各种相关教程的数量也开始增长,但是就我的观察而言,很多教程并没有做到基本的可读性与可访问性。而这篇文章的目的就是介绍如何做出基本美观的教程。当然在这篇文章我不会提及如何创作教程内容,这篇文章的主要关注点是,教程创作的流程、部署以及发布。

可读性和可访问性

首先要回答到是,什么是可读性和可访问性。我们先从可读性开始说明,可读性包括很多的方面:字体排版、网页的配色等。要一一说明显然是不现实的,这里我们就用一个例子说明。

image-20201105123703489

image-20201105123738827

这是同一段文本经过不同的排版方式后呈现出来的效果,我相信经过这个对比,应该很容易体会出为什么是什么可读性,以及为什么可读性是重要的。

接下来,是可访问性,你应该优先把教程作为一个的网页进行发布,而不是通过例如:加密的百度网盘分享一个 docx,来分发你的教程。

我们就以「加密的百度网盘分享一个 的 docx」作为例子,来说一下为什么这个是一种不好的方法。

首先加密的百度网盘就意味的一件事,这个教程是难以传播的,先不论如果通过百度网盘访问你的教程,还需要下载文件(并且忍受缓慢的速度),光是访问需要输入密码这件事,其实就是在减少你的教程的访问数量。

其次我们来讲一下分发 docx 文件为什么不好,你得先明确一点,docx 是 Microsoft Office 的格式而 Minecraft 是个跨平台的游戏,你的读者不是一定只是 Windows 用户,也可以是 macOS 和 Linux 用户,哪怕是 Windows 用户,也不一定就买了 Office,这一点就决定了对于他们来说打开 docx 其实并不是一件非常方便的事情。另外用 docx 来分发你的教程,如果你的教程需要持续更新,读者也需要不时的重新下载一遍,这个显然是不可取的。

有的作者可能会选择将自己的教程内容直接发布在某个论坛之上。但是这其实也不是一个非常好的办法,因为不同的论坛有不同的规定,你的教程很有可能在某天就变得无法访问了,这相当于将你的教程拱手送给了论坛。

而一个单独的网页则没有以上的问题,读者只需要输入地址即可访问,也不需要不断的重复下载一个文件,而且你可以自己控制网页的样式,并且可以做到自动化:在每次更新之后只要经过简单的步骤就可以更新对应的网页。

撰写

你可以使用 Markdown 作为你的写作格式,一切根据你需要来,有些作者可能会更加习惯 LaTex 等格式。关于 Markdown 的语法,这里就不多加说明了,非常容易学习。之后你得选定一个网页生成器,对于长篇的教程来说,合适的工具是各种电子书生成器,比如 mdbook(可能有的作者会使用 GitBook,但是 Gitbook 这个项目已经停止更新了,请不要使用了)。

接下来你就可以通过这些工具,写出一个精美的教程了。

构建与发布

在你写了一定内容的教程之后,你接下来面临的一个问题就是如何发布你的教程,这里推荐使用 Github Pages 的功能,你不需要有自己的域名和服务器,可以直接发布静态网页。当然,很多作者可能会将教程在本地构建完成,然后再通过 Git 同步到 Github 仓库上,但这其实不是一种好的方式,构建工作应该自动进行。你可以通过类似 Github Action 这样的工具,自动的构建与发布你的教程,这里是 Neutrino 的例子

最后呈现出来的效果是,我只要修改好内容,然后向 Github push 修改好的内容,对应的网站会自动的更新与发布。

一些额外事项

在开始写作一个教程的时候,你需要选择一个合适的许可证,这个许可证会在一定程度上保护你的权利,这里建议使用 Creative Commons 系列许可证。