本页面包含 Google 文档季接受的技术写作项目的详细信息。
项目摘要
- 开源组织：
- ESLint
- 技术文档工程师：
- Khawar
- 项目名称：
- 重新整理/重写配置文档
- 项目时长：
- 标准时长（3 个月）
Project description
摘要
此项目的目标是重构 ESLint 的配置文档，并创建有效的信息架构。这样可以简化导航，还能提高文档的易用性和实用性。
项目摘要 目前，ESLint 的配置文档 (https://eslint.org/docs/user-guide/configuring) 在单个页面上提供了大量信息。尽管页面上有标题、副标题和适当的段落，但文档可能还是会让人感到信息量过多。无法导航到页面的特定部分，这会让对特定部分感兴趣的用户感到沮丧。由于缺乏组织性，信息也可能会丢失，无法发挥作用，并要求用户付出额外的努力。
不过，这些问题可以通过一系列小心谨慎的步骤来解决。我建议在此次重组的第一步中进行内容审核。内容审核不仅有助于找出信息呈现方式存在的问题，还能凸显内容本身的不足（例如信息已过时或不完整）。然后，我打算创建信息架构 (IA)，以揭示知识网络。这样，我们就能够根据各种主题将信息汇总到一起，并找出各种密切相关的主题之间的关联。然后，我们会利用通过这两种做法获得的见解将单页文档划分为多页。然后，您可以在 Markdown 中链接和交叉引用整个软件包。因此，我们将推出更加井然有序的配置文档版本，更易于浏览和理解。
动机 尽管我使用开源软件已有相当长的时间，但我对该术语的熟悉程度还是相当新的，就像我对 linting 软件的了解一样。当我开始通过 edX 学习 Python 时，我确实很疑惑，微小的错误是如何搞乱整个代码的。我认为，如果能以某种方式测试代码并找出错误，那就太好了，后来我了解到了“linting”一词。我还没有正确使用 linting 软件，但我相信，这些工具日后会让我的工作变得更加轻松。
我拥有电气工程背景，并有一定的编程经验，因此可以更好地理解编码问题和程序员的要求。此外，我拥有技术和专业沟通领域的硕士学位，因此我会站在用户的角度，努力为用户简化生活。我的技能和专业知识非常适合这项工作，可以为 ESLint 文档增添价值。
目标 此项目的总体目标是确保 ESLint 配置页面上的文档易于理解，不会让用户感到不知所措。让内容导航变得简单方便，且没有任何复杂问题，这对项目的成功至关重要。 该项目的重要目标如下。 - 进行全面的内容审核 - 创建信息架构以了解信息流向 - 改进信息架构以重新整理文档 - 确定内容不同部分之间的链接和引用 - 根据需要重写/修改文档的部分，以满足重新配置要求
- 确保内容灵活且可重复使用
项目说明配置 ESLint 是一项重要功能，可让 ESLint 进行自定义。对配置感兴趣的用户在给定时间内肯定会对一两个方面感兴趣。因此，引导用户找到他们感兴趣的特定主题，以便高效地为他们提供解决方案，这一点至关重要。ESLint 的配置文档目前包含大量实用信息，但其编排方式可能会让用户感到不知所措、沮丧和迷失。例如，如果用户有兴趣了解如何在 ESLint 中使用第三方插件，则必须向下滚动，查看有关指定解析器、环境和全局变量的讨论。整个实践操作会让用户感到厌烦，并可能导致他们离开网站。 同样，如果用户位于页面中间，并且想要转到特定部分或只是浏览类似的主题，这对他们来说并非易事，因为没有向用户提供此类帮助。这些问题需要立即予以关注，因为任何文档的质量，无论其草稿有多好，都取决于其实用性。在接下来的讨论中，我会提出针对这些问题及其他相关问题的解决方案。
内容审核 重新整理配置文档的第一步是进行全面的内容审核。审核旨在找出一些关键问题，例如内容过时、重复、缺失等。我们会将生成的内容审核电子表格分享给管理团队和文档团队，以征求他们的反馈。这有助于制定新的策略来构建和呈现文档。
创建信息架构 如需了解配置文档中的知识网络或信息流，创建信息架构 (IA) 可能很有帮助。内容审核的结果将是理解和发展信息流的良好基础。然后，我们将创建改进版信息架构，以便更好地组织和展示文档。经过改进的 IA 不仅会重构当前内容，还会识别文档各个部分之间的链接和分支，从而创建高效的网络。例如，“配置规则”内容后面可以跟一个指向“使用内嵌注释停用规则”的链接。您还可以识别其他此类链接，从而在文档的不同部分之间建立关联。
目录 内容审核和 IA 将提供足够的信息来创建详细的目录，其中包含指向文档中特定部分和子部分的链接。为每个部分创建单独的文件并向其他部分添加适当的引用，可以为整套文档增添价值。您可以为着陆在配置文档中的用户创建目录，以便他们在网站上顺利完成整个流程。目录可以包含所有第一级和第二级标题，以便简明扼要地概括内容。例如，Prettier (https://prettier.io/docs/en/index.html) 使用这种方法来整理文档。
所有文档都将使用 Markdown 创建，以保持简单有序。我们要特别注意，确保该文档可重复使用，因为日后它可能会不断增加和更改。
所用工具 在处理项目时，以下一些重要工具会派上用场： - Draw.io，可根据需要为 IA 创建插图 - Atom（或类似编辑器），用于以 Markdown 格式撰写和修改文档
- GitHub，以确保文档的版本控制
里程碑 从提交提案到完成项目，以下暂定里程碑可确保项目按时完成，并在过程中保持正确的流程。
2020 年 7 月 10 日 - 2020 年 8 月 16 日：提案审核和选择 我将仔细阅读 ESLint 文档，并掌握完成项目所需的技能（例如 Markdown 编写、在 GitHub 上协作）。我还将通过 GitHub 为文档做出贡献，并与其他人互动，以便更好地了解文档。
2020 年 8 月 17 日至 2020 年 9 月 13 日：社区互动 在社区互动期间，我会根据与导师和相关团队的讨论优化我的提案。我还会根据需要修改目标和里程碑。此外，我会确保列出用于处理项目的候选工具。
2020 年 9 月 14 日至 2020 年 9 月 19 日：内容审核 首先，我会对配置文档进行全面的内容审核。目的是突出显示内容及其呈现方式方面的问题。
2020 年 9 月 20 日 - 2020 年 9 月 25 日：信息架构 (IA) 完成内容审核后，我将创建配置文档的 IA。我将重点介绍如何以易于理解的方式呈现知识网络。这有助于改进信息流。
2020 年 9 月 26 日至 2020 年 9 月 30 日：链接和参考文档 在此阶段，我将分析 IA，以绘制文档各部分之间的链接和参考文档。我还将创建所有部分的层次结构，从而改进该过程中的 IA。
2020 年 10 月 1 日至 2020 年 10 月 3 日：最终映射 然后，我将利用通过内容审核和 IA 获得的分析洞见，创建最终映射，以便在重新整理后的配置文档中实现。此全面的图表将包含目录、主题层次结构，以及文档各部分之间的链接和交叉引用列表。
2020 年 10 月 4 日至 2020 年 10 月 5 日：讨论 在编辑文档之前，我会向导师和相关团队展示自己的发现和计划。他们的反馈有助于我们优化方案并根据需要进行更改。
2020 年 10 月 6 日 - 2020 年 10 月 20 日：重写和编辑 在此期间，我会修改和更新需要改进的文档部分。配置文档的某些部分可能会被重写，或者可能会添加一些新内容。在此阶段，重点是确保文档准确、及时更新、灵活且可重复使用。
2020 年 10 月 21 日至 2020 年 10 月 25 日：修改和链接 在此阶段，我将检查自己的工作，以消除语法和结构错误，并仔细检查自己的工作是否准确。此外，我还会根据信息架构在各部分之间添加链接和参考信息，以确保本文档符合之前设计的知识图谱。
2020 年 10 月 26 日至 2020 年 10 月 31 日：提交最终版本 我将链接所有 Markdown 文件，创建目录，并与导师分享草稿。这将作为初稿提交，形式为完整文件包。
2020 年 11 月 1 日至 2020 年 11 月 5 日：首次审核 在这 5 天内，我将与导师讨论初稿。我会征求他们的反馈，并与他们讨论我的想法，以列出需要进行的修改。
2020 年 11 月 6 日至 2020 年 11 月 12 日：首次修改 在导师的反馈帮助下，我将修改文档的初稿。实际的修改将取决于评论和反馈的性质，但重复使用、准确性和灵活性将是编辑阶段的核心目标。
2020 年 11 月 13 日至 2020 年 11 月 15 日：第二次审核 完成初步修改后，我会再次与导师和相关团队讨论进度。这些讨论将侧重于对第一版所做的编辑，还会强调在编辑过程中可能出现的任何其他问题。
2020 年 11 月 16 日至 2020 年 11 月 19 日：第二次修改 我将在这四天内专门编辑该文档。我们会与导师讨论所生成的版本，以确定最终版本。完成此阶段后，文档将进入最终状态，可以上传到网站和 GitHub 代码库。
2020 年 11 月 20 日至 2020 年 11 月 23 日：上传到网站 完成所有必要的修改后，我们会将文件上传到网站。在此过程中遇到的任何问题都会得到相应处理，因为我们还有几天的时间来完善相关文档。
2020 年 11 月 24 日至 2020 年 11 月 28 日：项目报告 我们将在这 5 天内创建项目的详细报告。所呈现的目标、问题、问题和解决方案将成为项目报告的一部分。我们会将该报告分享给导师，以便他们提供反馈。
2020 年 11 月 29 日至 2020 年 11 月 30 日：最终提交 将项目、所有文件和项目报告提交给导师。我们将通过与导师和相关团队开会/讨论的方式，对整个项目进行审核。
在整个项目过程中，我会不断咨询导师，获取他们的宝贵反馈。所有这些里程碑都可以根据在社区互动和提案审核阶段与导师的讨论进行更改。
关于我 我拥有北卡罗来纳州立大学的电气工程学士学位和技术与专业沟通硕士学位。我拥有技术和专业写作和编辑、沟通和内容管理、Web 和移动设备易用性研究以及教学设计方面的经验。我曾在一家在线出版物 (Global Village Space) 担任副编辑，并在杜克大学杜克大学福吉大学担任公关实习生。除此之外，我还对创意写作感兴趣。