一个有吸引力的系统或产品的关键是什么？ 这一切都始于最重要的自述文件。 README 是项目的第一页——它通常是您给用户和贡献者的第一印象。
一个好的自述文件应该让用户了解项目的内容、使用的语言、条款和条件、你的项目可以做什么、显示正在运行的应用程序的屏幕截图等。 自述文件的用户可以是招聘人员、您未来的老板或客户。 因此，需要注意的是，项目的自述文件应包括项目的内容、原因和方式。 清楚地描述您的项目或产品的目的、功能、使用方法、安装步骤和其他信息非常重要。 确保您的自述文件易于阅读和理解，并向用户或其他开发人员提供有用的信息，以及可能不适合自述文件的链接和进一步说明，以避免不必要地搜索所有其他文件。 这可能会导致用户失去兴趣并转向下一个潜在员工。
写一个好的项目自述文件非常重要，我怎么强调都不为过。 用户不仅在寻找有关项目本身的信息，而且还可以看到您的文档技能和对细节的关注，这可以使您更容易找到工作。
如果你读过我的其他文章，你可能已经注意到，除了编程之外，学习其他技能对我的职业生涯是多么重要，这些技能最终帮助我找到了工作。 好的文档就是其中之一。 以下是一些可以帮助您的指导性问题：该项目是关于什么的？
你为什么开发它，你的动机是什么？
它解决了什么问题？
你学到了什么？
是什么让您的项目脱颖而出？
我将向您展示如何将这些问题转换为文本。 描述：项目的目的和描述，以便阅读您的作品集的人可以在阅读项目信息的最初几秒钟内了解项目。 技术栈技术堆栈包括项目使用的编程语言、库和框架（例如 python、react 等）。 如果您有一个使用外部公共 API 的前端应用程序，请提及这一点。
与项目相关的用户界面设计实例。 如果您的项目具有用户界面，则可以插入用户界面的 gif、** 或图像。
如果它是在终端上运行的应用程序，您可以创建一个 GIF 来展示如何使用它。 这有助于了解如何与应用程序交互，以及人们在运行项目时将看到的内容。 GIF 和其他视觉效果永远无法取代在文档中提供特定细节的工作，但它们绝对可以在展示项目的用户界面时提供额外的“哇”元素。 它们使读者能够轻松快速地访问有关项目的大量信息，这是提高采用率并最终为项目做出贡献的关键。
特征如果你的项目有很多功能，你应该添加它们特征部分并在此处列出它们。
如何运行项目有关如何设置、运行和使用项目的说明。 如果有人想从头开始项目，那很好，他们应该在项目的自述文件中找到他们需要知道的一切，而无需您的任何帮助。 如果它很简单，你可以把它包含在自述文件中。 如果描述较长，还可以将描述文件添加到引用项目中。
您还应该使用 Netlify 来托管您的项目，以便用户可以打开已部署的应用程序并立即使用它来查看其工作原理。 （请记住，并非每个查看 GitHub 个人资料的招聘人员都对如何在本地构建项目有很好的了解。 ） 创建自述文件MD 文件代表 Markdown，一种具有简单文本格式语法的轻量级标记语言。 这是一种非常简单的语言，用于为 GitHub 创建美观且美观的自述文件。 因此，您可以使用典型的 Markdown 语言。
以下是我三年前申请工作的两个初学者项目示例。
一个好的自述文件没有单一的标准，每个项目都有不同的目标和期望。 以下是一些针对不同类型项目的自述文件。
npm 是最流行的 j**ascript 包管理器。 鉴于这是一个包管理器，很难直观地解释该项目。 该项目在保持自述文件本身简单、非常相关以及指向更复杂和更详细信息的链接方面做得很好。
lar**el 自述文件提供了许多文档链接，但更重要的是，它提供了社区学习资源的链接。 其中包括 Lar**el Bootcamp，它向您展示了如何快速启动和运行，以及 Laracasts，一个全面的教程库。 根据开发人员的说法，这些资源是 Lar**el 最受赞赏的方面之一，因此尽早将其传达给潜在用户（即在自述文件中）非常重要。
VScode 无处不在，它也有一个很棒的自述文件。 它显示了 IDE 在使用过程中的外观，因此用户可以立即了解产品是什么。 这些产品比 Appsmith 等内部工具开发人员更成熟、更易于理解，因此他们不一定需要更多的可视化。 VSCode 提供了简短的产品描述，并提供了指向更详细信息的链接。
Trekhleb的自制机器学习，这个项目更注重教育而不是产品。 机器学习的学习可能非常复杂，因此像这样的项目可以从良好的可视化和链接中受益。 本项目充分利用可视化，帮助学生在机器学习领域形成心智模型，涉及相当多的知识。 有很多不同的算法需要学习，但是一旦你想到了它们，就有一种合乎逻辑的方法来对它们进行分类，这张图很好地说明了这一点。
原文链接：本文已翻译并发表。