本页面包含有关 Google 文档季可接受的技术写作项目的详细信息。
项目摘要
- 开源组织：
- 知识共享
- 技术文档工程师：
- nimishnb
- 项目名称：
- 词汇使用指南
- 项目时长：
- 标准时长（3 个月）
Project description
项目摘要
Vocabulary 具有巨大的潜力，可以用作构建网站的主要界面组件库。它需要的是一份功能强大且对外行人友好的操作指南。重要的开发者信息（例如组件指南、使用规范和配置调整）是任何文档的基本组成部分。这不仅可以鼓励现有用户了解词汇量如何继续增长并达到新的里程碑，还可以促进人们在相对较新的项目中使用词汇表。作为实习生，我所取得的理想成效不仅需要编写一份关于使用现有组件的实用指南，还要针对词汇、Vue-Vocabulary 和字体设计和开发一个首页（并给出每个页面的集成文档）。
项目计划
问题：文档是决定某个开源库成功与否的主要原因之一。在选择适合的技术栈来构建其应用时，开发者会想到一个主要问题：“该库是否记录良好？是否维护良好？是否有相当多的使用和错误支持？”。这些正是我们在实施这个项目创意时应该问自己的问题。从软件工程的角度来看：
要求分析：您迫切需要一个符合我们需求的简明整合文档。缺乏文档有损于开源应用的未来视角，并且迄今为止是一个不可忽略的必要组件。指向这些文档的链接应是一个具有吸引力的首页，能够立刻吸引人们的兴趣。文档应有条不紊地处理，从而实现顺畅的沟通。
规范：可以根据具体要求确定规范。文档内容可以由 CC netlify 网站中的数据以及 semantic-ui、scikit-learn、numpy、bootstrap 等知名文档的一些灵感构成。此任务的输出结果是必须提供的着陆页和完整的文档指南。
目前，有关词汇、Vue-Vocabulary 和字体的一些常见问题：
此类文件缺少文件；即使有文件，其中的部分内容也会散布在整个 netlify 网站上。这不会让用户、开发者或外部贡献者使用我们的库。
如需转到特定组件并复制其对应的代码，需要执行额外的点击操作。如果在 Google 上搜索“标签页组件 CC 词汇”之类的内容，系统并不会返回所需信息。文档指南中的“搜索”选项将极大地改善用户体验。
以文字形式详细说明的组件，描述不明显的细节。
没有实时运行选项。JSFiddle 等多个网站均支持实时运行，这让开发者无需运行整个应用来查看其运行情况，即可了解组件。
解决方法
有多种解决方案可能。不过，我在这里会讨论几个问题，并在结论部分展示我的最终解决方案：-
= 使用 readthedocs 是为开源库编写文档的已知解决方案。它基于 Python 文档工具 Sphinx 开发。
优点：
- 以太坊 (Solidity) 等组织使用的一种广泛接受的文档生成形式。
- 结构最合理的文档。
- 免费的静态托管。
缺点：
- 缺乏对样式的绝对控制。
= 使用 Sphinx 我们也可以在文档部分使用 Sphinx 本身，它为我们的所有用途提供了良好的功能。
优点：
- 最受欢迎的 Python 文档工具。
- 还支持文档搜索。
- 可以使用自定义 CSS 覆盖默认 CSS；部分使用 .rst 文件控制 HTML。
缺点：
- 这涉及使用 Python 进行编码和重构文本格式 (.rst)，这不同于建议的项目语言。
= 使用 Jekyll 主题 Jekyll 主题已集成到 GitHub 页面中，并且有一些现成的模板，可根据需要进行自定义。
优点：
- 适用于各种用途的现成文档主题。
- 默认 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 文档中划分内容的方式。语义界面网站（使用 StoryBook）给我留下了深刻的印象，该网站采用极简设计风格，只需点击几下就能轻松了解自己想要的内容。除了语义界面之外，我还研究了 Material Design、Primer、Bootstrap、Carbon Design 等，将其用作我工作的界面样式指南和设计系统。我们还可以参考现成的 Jekyll 文档主题，从中寻找灵感。