本页面包含有关 Google 文档季可接受的技术写作项目的详细信息。
项目摘要
- 开源组织：
- ESLint
- 技术文档工程师：
- 卡瓦尔
- 项目名称：
- 重新整理/重写配置文档
- 项目时长：
- 标准时长（3 个月）
Project description
摘要
此项目的目标是重新组织 ESLint 的配置文档，并创建有效的信息架构。这不仅能简化导航过程，还能提高文档的易用性和实用性。
项目摘要 在当前状态下，ESLint 的配置参数 (https://eslint.org/docs/user-guide/configuration) 提供了大量信息。尽管页面上存在标题、子标题和适当的段落，但文档中可能会让人感到不知所措。无法导航到该网页的特定部分，这会令对特定部分感兴趣的用户感到失望。信息由于缺乏组织结构，也可能会丢失，达不到其用途，需要用户投入额外的精力。
不过，这些问题可以通过一系列谨慎的措施来解决。我提议进行内容审核，这是此次重组的第一步。内容审核不仅有助于找出信息呈现方式方面的问题，还能突出内容本身的缺点（例如信息已过时或不完整）。然后，我计划创建信息架构 (IA)，用于展示这个知识网络。这样，我们就能根据各种主题对这些信息进行归类，并找出各种密切相关的主题之间的关联。通过这两种做法获得的数据洞见随后将用来将单页文档分成多个页面。然后，您可以在 Markdown 中关联整个软件包并对其进行交叉引用。因此，我们将推出结构更清晰的配置文档，更便于浏览和理解。
动机 尽管我使用开源软件已经有一段时间了，但我对这个术语的熟悉，就像我对 Lint 软件的了解一样。开始通过 edX 学习 Python 时，我很想知道微小错误会如何使整个代码变得混乱。我本来以为最好能测试一下您的代码，并找出错误，然后我发现了“执行 lint 请求”这一术语。我还没有适当地使用 lint 检查软件，但我确信在未来几天内，这些软件将会让我的工作更轻松。
凭借电气工程背景和一些编程经验，我能够更好地理解编码问题和程序员的要求。此外，我在技术和专业沟通领域拥有研究生学位，让我成为 Google 用户的代言人，努力让人们的生活更轻松。我的技能和专业知识将很好地融入该项目，从而为 ESLint 文档增添价值。
目标 此项目的主要目标是确保 ESLint 配置页面上的文档易于理解，不会让用户感到应接不暇。务必要让内容导航简单且不受所有复杂功能的影响，这对该项目的成功至关重要。 该项目的重要目标如下。 - 进行全面内容审核 - 创建信息架构，了解信息流 - 改进信息架构以重新整理文档 - 标识内容不同部分之间的链接和参考信息 - 重写/编辑文档的各个部分（如有必要）以满足重新配置要求
- 确保内容灵活且可重复使用
项目说明 ESLint 配置是一项重要功能，使 ESLint 可自定义。对配置感兴趣的用户无疑会在指定时间内对一两个方面感兴趣。因此，务必要引导用户前往他们感兴趣的特定主题，从而高效地为他们提供解决方案。ESLint 配置文档的当前状态包含大量有用的信息，但其组织方式会让用户感到不堪重负、沮丧和困惑。例如，如果有人有兴趣了解在 ESLint 中使用第三方插件时，必须向下滚动浏览有关指定解析器、环境和全局变量的讨论。整个这种做法对用户来说非常累，并且可能会迫使他们离开网站。 同样，如果用户位于网页的某个位置，想要前往特定的版块或只想查看类似的主题，这对他们来说也并非易事，因为不会向用户提供此类帮助。这些问题需要立即加以关注，因为任何文档的质量（无论草稿有多详尽）都取决于其实用性。 我就这些问题以及接下来的讨论中其他相关问题提出解决方案。
内容审核 重新整理配置文档流程的第一步是进行全面的内容审核。审核的目标是发现一些关键问题，例如内容过期、重复、缺少内容等。系统会将最终创建的内容审核电子表格与管理团队和文档团队分享，以征求他们的反馈。这将有助于制定新的策略来组织和展示文档。
创建信息架构 要了解配置文档中的知识网络或信息流，创建信息架构 (IA) 会很有价值。内容审核的结果将为了解和发展信息流打下坚实的基础。随后，我们将开发信息架构的改进版本，以便更好地整理和展示文档。这一改进的信息架构不仅会重新构建当前内容，还会识别文档各个部分之间的联系和分支，从而形成高效的网络。例如，在“配置规则”相关内容的后面可以跟一个指向“通过内嵌注释停用规则”的链接。系统也可以标识其他此类链接，从而在文档的不同部分之间建立关系。
目录审核和信息架构将提供足够的信息来创建详细的目录，其中包含指向文档中特定章节和子部分的链接。为每个部分创建单独的文件并为其他部分添加适当的引用，可提高整个文档集的价值。可以为访问配置文档的用户创建目录，以方便其浏览网站。目录可包括所有第一级和第二级标题，以确保内容简洁而全面。例如，Prettier (https://prettier.io/docs/en/index.html) 就是这样做的一种做法来整理文档。
所有文档都将使用 Markdown 创建，以确保内容简洁且条理清晰。我们会特别注意，确保相关文档可以重复使用，因为文档将来可能会增加和更改。
要使用的工具 一些在开展项目时可以用到的重要工具包括 - Draw.io，用于根据需要为信息架构绘制插图 - 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) 完成内容审核后，我将创建配置文档的信息架构。我将着重以易于理解的方式呈现知识网络。这将有助于改善信息流。
2020 年 9 月 26 日 - 2020 年 9 月 30 日：链接和参考文档 我将在此阶段分析信息架构，以找出文档各部分之间的链接和参考文档。此外，我还将为所有部分创建一个层次结构，以便改进流程中的信息架构。
2020 年 10 月 1 日至 2020 年 10 月 3 日：最终地图 借助通过内容审核和信息架构获得的数据洞见，我随后将制作出最终地图，并在重新整理的配置文档中予以实施。该综合地图将包含一个目录、一个主题层次结构，以及一个文档各部分之间的链接和交叉引用列表。
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 日：第一次审核 在这五天里，我将与我的导师讨论初稿。我会收集他们的反馈，与他们讨论我的想法，列出需要做出的修改。
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 日：项目报告 在这五天的时间内将创建一份项目的详细报告。项目报告中会涵盖目标、困难、问题以及所提供的解决方案。此报告将分享给导师以获得反馈。
2020 年 11 月 29 日至 2020 年 11 月 30 日：最终提交 项目以及所有文件和项目报告将提交给导师。我们会与导师和相关团队召开会议/讨论，审核整个项目。
在整个项目过程中，我会一直咨询这些导师，收集他们的宝贵反馈。所有这些里程碑都可以根据在社区凝聚和提案审核阶段与导师的讨论而改变。
关于我 我拥有北卡罗来纳州立大学电气工程专业的学士学位，以及北卡罗来纳州立大学技术与专业沟通专业的研究生学位。我拥有以下领域的经验：技术和专业的写作与编辑、沟通和内容管理、网页和移动设备易用性研究，以及说明设计。我曾在杜克大学担任过在线出版物 (Global Village Space) 的副编辑，还在杜克福吉大学担任沟通实习生。除此之外，我还对创意写作很感兴趣。