本页面包含 Google 文档季接受的技术写作项目的详细信息。
项目摘要
- 开源组织：
- 知识共享
- 技术文档工程师：
- nimishnb
- 项目名称：
- 词汇使用指南
- 项目时长：
- 标准时长（3 个月）
Project description
项目摘要
Vocabulary 非常适合用作网站构建的主要界面组件库。它需要的是一份实用且易懂的操作指南。重要开发者信息（例如组件指南、使用规范和配置调整）是任何文档的重要组成部分。这不仅会鼓励现有用户了解词汇如何不断发展并达到新的里程碑，还会促进在相对较新的项目中使用词汇。作为实习生，我希望取得的理想成效不仅包括撰写有关使用现有组件的实用指南，还包括为 Vocabulary、Vue-Vocabulary 和 Fonts 设计和开发首页（最终为每项提供集成文档）。
项目计划
问题：文档是决定某个开源库能否取得成功的主要原因之一。开发者在选择合适的技术栈来构建应用时，会考虑一个主要问题：“该库是否有详细的文档？它是否维护良好？是否有可观的使用和错误支持？”。这些正是我们在推进此项目想法时应该问自己的问题。从软件工程的角度来看：
要求分析： 我们迫切需要有一个简明的整合文档来满足我们的需求。缺少文档会影响开源应用的未来前景，而且文档是至关重要的组成部分，不容忽视。链接到这些文档的首页应具有吸引力，能够立即吸引用户的兴趣。文档应井然有序，以便顺畅浏览。
规范：可以根据要求确定规范。文档中的内容可以从 CC netlify 网站中的数据中构成，并从 semantic-ui、scikit-learn、numpy、bootstrap 等知名文档中获得一些灵感。此任务的输出将是所需的着陆页和完整的文档指南。
目前与词汇、Vue-Vocabulary 和字体相关的一些常见问题：
缺少文档；即使有，其部分内容也散布在 Netlify 网站的各个角落。这并不会使用户、开发者或外部贡献者无法使用我们的库。
如需前往某个组件并复制其对应的代码，需要额外点击。在 Google 上简单搜索“标签页组件 CC 词汇”等字词不会返回所需信息。文档指南中的搜索选项可以极大地改善用户体验。
对组件进行更详细的文本说明，说明不明显的细节。
没有实时运行选项。JSFiddle 等各种网站都支持实时运行，这样开发者无需运行整个应用即可了解组件的运作方式。
解决方案
有多种可能的解决方案。不过，我会在这里介绍其中一些，并在结论部分介绍最终解决方案：-
= 使用 readthedocs readthedocs 是一个为开源库编写文档的知名解决方案。它基于 Python 文档工具 Sphinx。
优点：
- 以太坊 (Solidity) 等组织广泛接受的文档生成形式。
- 结构最优的文档。
- 免费的静态托管服务。
缺点：
- 无法完全控制样式。
= 使用 Sphinx 我们也可以在文档部分原生使用 Sphinx，它提供了适用于我们所有用途的强大功能。
优点：
- 最受欢迎的 Python 文档工具。
- 还支持文档搜索。
- 默认 CSS 可以被自定义 CSS 替换；使用 .rst 文件对 HTML 进行部分控制。
缺点：
- 需要使用 Python 和重构文本格式 (.rst) 进行编码，这与建议的项目语言不符。
= 使用 Jekyll 主题 Jekyll 主题集成在 GitHub 页面中，并且一些现有的模板可以根据需要进行自定义。
优点：
- 适用于各种用途的现成文档主题。
- 您可以使用自定义 CSS 和样式替换默认 CSS 和样式，还可以控制 HTML。
- 提取默认的 Primer CSS 以构建页面。
- 轻松与 GitHub 页面集成。
缺点：
- 可能无法提供最佳的文档结构。
=使用 GitHub 页面 使用标准 GitHub 页面构建静态网站（HTML、CSS、JS）。
优点：
- 对相关的几乎所有内容拥有完全控制权。
- 在确定布局、颜色和样式方面具有极高的灵活性。
- 轻松使用词汇组件。
- 轻松嵌入代码段和实时运行链接。
缺点：
- 这可能是一种更耗时的方法。
= 使用 Haroopad 这提供了一个替代的 Markdown 解决方案。
优点：
- 只需编写少量繁琐的代码。
- 重点是完美地编写文档。
缺点：
- 无法控制 CSS。
- 不一定拥有最好的社区支持。
- 可能不支持 MDX。
= 使用 MKDocs 这提供了另一种替代 Markdown 解决方案。
优点：
- 需要编写的代码会尽可能少（再次）。
- 编写更多代码，减少代码编写。
缺点：
- 无法控制 CSS。
- 社区支持可能不是最佳。
- 使用 Python；可能还需要启动 Amazon S3 实例。
= 使用 VueJS +StorybookJS 这种方法在 Vocabulary 及其姊妹代码库中很常用。
优点：
- 坚持使用过去工作经验证明绝对可行的技术。
- 熟悉代码库。
- 此领域没有可靠的技术。
缺点：
- 也可能存在一些更简单的选项来实现相同的目的。
总而言之，我认为涉及 VueJS+Storybook 方法（HTML、CSS、JS）的方法似乎最适合，因为我也能接受。不过，这也意味着我们不会在开发此应用时完全不考虑这些因素。使用 CC-Vocabulary 组件也非常简单。不过，在确定文档结构时，我们必须考虑在 Readthedocs 文档中将内容划分为子标题的方式。Semantic-UI 网站（使用 StoryBook）给我留下了深刻印象，因为它采用极简设计，用户只需点击几下，即可轻松了解所需内容。除了 Semantic-UI 之外，我还查看了 Material Design、Primer、Bootstrap、Carbon Design 等，以便将其用作工作中的界面样式指南和设计系统。我们还可以查看现成的 Jekyll 文档主题，从中获得灵感。