程序员如何写创建一份高质量的README.md 文件?

最新推荐文章于 2024-10-31 15:40:02 发布

原创最新推荐文章于 2024-10-31 15:40:02 发布 · 1.1k 阅读

28 ·

CC 4.0 BY-SA版权

文章标签：

#远程工作 #学习 #程序人生 #程序员

本文探讨了如何编写一个出色的项目自述文件，包括清晰描述项目目的、技术堆栈、用户界面截图、功能列表、运行指南，以及设计简洁易读的Markdown格式。实例分析了npm、Laravel和VSCode等项目的自述文件策略，强调了教育项目如机器学习的可视化效果的重要性。

一个系统或者产品要想吸引人，关键是什么？这一切都要从最重要的自述文件开始。自述文件是项目的首页——它通常是你给用户和贡献者留下的第一印象。

一份优秀的自述文件应该让用户了解项目的内容、使用的语言、条款和条件、您的项目可以做什么、显示正在运行的应用程序的屏幕截图等。

它为什么如此重要？

自述文件的用户可能是招聘人员、您未来的老板或客户。因此，需要注意的是，项目的自述文件应该包括项目的内容、原因和方式。

重要的是清晰地描述你的项目或产品的目的、功能、使用方法、安装步骤等信息。确保你的自述文件易于阅读和理解，并提供有用的信息给用户或其他开发者，并提供可能不适合 README 文件的链接和进一步说明，以避免不必要地搜索所有其他文件。可能会导致用户失去兴趣并转向下一个潜在员工。

编写一份良好的项目自述文件非常重要，我怎么强调都不为过。用户不仅在寻找有关项目本身的信息，而且还可以看到您的文档技能和对细节的关注，这可以让您更容易找到工作。

如果您读过我的其他文章，您可能已经注意到，除了编程之外，学习其他技能对我的职业生涯有多么重要，这些技能最终帮助我找到了工作。良好的文档就是其中之一。

自述文件中应包含哪些内容？

以下是一些可以帮助您的指导性问题：

该项目是关于什么的？
你为什么开发它，你的动机是什么？
它解决了什么问题？
你学到了什么？
是什么让您的项目脱颖而出？

我将向您展示如何将这些问题转换为文本。

可能的结构

描述项目的目的和描述，以便阅读您的作品集的人可以在阅读项目信息的前几秒钟内了解该项目。

技术堆栈 技术堆栈包括您的项目使用的编程语言、库和框架（例如：Python、React 等）。如果您有使用外部公共 API 的前端应用程序，请提及这一点。

与项目相关的用户界面的设计示例。如果项目有用户界面，您可以插入用户界面的 GIF、视频或图像。
如果它是在终端上运行的应用程序，您可以创建一个 GIF 来展示如何使用它。这有助于了解如何与应用程序交互以及人们在运行项目时会看到什么。

GIF 和其他的视觉效果永远无法取代文档提供具体细节的工作，但在展示项目的用户界面时，它们绝对可以额外提供让读者“哇”起来的因素。它们可以让读者轻松快速地获取有关项目的大量信息，这是提高采用率并最终为项目做出贡献的关键。

功能如果您的项目有很多功能，您应该添加“功能”部分并在此处列出它们。

如何运行项目 有关如何设置、运行和使用项目的说明。如果有人想从头开始该项目，这很好，他们应该在项目的自述文件中找到他们需要了解的所有内容，而不需要您的任何帮助。

如果很简单，您可以将其包含在自述文件中。如果说明较长，您还可以在参考项目中添加一个说明文件。

您还应该使用 Netlify 托管您的项目，以便用户可以打开已部署的应用程序并立即使用它来查看它是如何工作的。（请记住，并非每个查看您 GitHub 个人资料的招聘人员都充分了解如何在本地建立项目。）

如何设计自述文件的样式？

创建README.md文件的代表Markdown，一种轻量级标记语言，具有简单的文本格式化语法。它是一种非常简单的语言，用于为 GitHub 创建美观且美观的自述文件。

因此，您可以使用典型的 Markdown 语言。

下面我三年前申请工作的初学者项目的两个例子。

一些出色的自述文件的例子

好的自述文件没有唯一的标准，每个项目都有不同的目标和期望。这里分享一些不同类型项目的自述文件。

npm 是最流行的 JavaScript 包管理器。鉴于这是一个包管理器，所以很难通过视觉效果来解释这个项目。这个项目在自述文件本身的简单性方面做得很好，表述非常切题，也会链接到更复杂更详细的信息。

Laravel 自述文件提供了大量文档链接，但更重要的是，它提供了社区学习资源的链接。其中包括介绍如何快速启动和运行的 Laravel Bootcamp ，以及综合视频教程库 Laracasts。开发者认为，这些资源是 Laravel 最受赞赏的地方之一，因此尽早（也就是在自述文件里）向潜在用户传达这一点非常重要。

VSCode 无处不在，而且它还有一个很棒的自述文件。它展示 IDE 在使用过程中的样子，这样用户就可以立即了解产品是什么。与 Appsmith 等内部工具开发者相比，这类产品更成熟，更容易为开发者所理解，因此不一定需要更多的可视化效果。VSCode对产品进行了简短、切中要点的描述，并提供了更详细信息的链接。

Trekhleb 的《自制机器学习》，一个更注重教育而不是产品的项目。机器学习学习起来会非常复杂，因此像这样的项目可以得益于良好的可视化效果以及链接。

这个项目充分利用了可视化效果来帮助学生形成机器学习领域的思维模型，因为这个领域涉及的知识面是相当大的。有很多不同的算法需要学习，但是记住它们之后，就有一种逻辑方法可以对它们进行分类，这张图很好地展示了这一点。

原文链接：https://dev.to/yuridevat/how-to-create-a-good-readmemd-file-4pa2?ref=dailydev，本文经翻译整理后发布。