hbuilder自述文件
以及为什么它也应该属于您。 (And why it should be yours as well.)
Confession and Resolution
认罪与解决
My approach used to be total procrastination, and I would wait until the end of a project (if at all) to address documentation. By the end of any decent-sized project, I felt overwhelmed going back to the start of what I had built in order to document it well.
我的方法曾经是完全拖延，并且我会等到项目结束(如果有的话)来解决文档问题。 在任何体面的项目结束时，我都觉得不知所措，可以追溯到为记录得很好而建立的项目的开始。
I even found that my mediocre documentation attempts were failing at times simply because I had lost touch with the evolutionary subject matter understanding I had developed over the course of the project. This evolutionary knowledge is really, really important to capture, because it represents the ingredients for accurate documentation.
我什至发现，我平庸的文档尝试有时会失败，这仅仅是因为我对项目过程中对主题的不断发展的理解失去了联系。 掌握这些进化知识确实非常重要，因为它代表了准确记录的要素。
In my ongoing effort to do hard things well, creating good documentation for my projects is something I’ve made a priority. While it may sound tedious or onerous, I have discovered that starting every new development effort with a simple README has completely changed my perspective on documentation.
在不断努力做好事情的过程中，为项目创建好的文档是我的首要任务。 尽管这可能听起来很乏味或繁重，但我发现以一个简单的README开始每项新的开发工作已经完全改变了我对文档的看法。
I now consider this approach my own mini version of Readme Driven Development. In fact, it’s become my favorite part of development. Okay, maybe that’s a bit hyperbolic, but this step is certainly among my favorite parts of development. When I cross the finish line on a project and find that the documentation is there waiting on me, 100% complete, it’s a great feeling!
我现在将这种方法视为我自己的自述驱动开发的迷你版本。 实际上，它已成为我最喜欢的开发部分。 好的，也许有点夸张，但这一步肯定是我最喜欢的开发部分。 当我越过项目的终点时，发现文档在等我，100％完成时，真是太好了！
Why have I become such a fan of the README?
为什么我会成为README的粉丝？
它鼓励我从文档开始任何新项目。 (It encourages me to start any new project with documentation.)
We all know that documentation is not considered the most glamorous part of a developer’s life, but we can probably all agree how thankful we are to find existing documentation when we peek into a new code base for the first time. What better way to encourage yourself to document the actual code than by making documentation the first commit to your repo?
我们都知道文档不是开发人员生命中最迷人的部分，但是我们可能都可以同意，当我们第一次探视新的代码库时，非常高兴能找到现有文档。 有什么比使文档成为对存储库的首次提交更好的鼓励自己记录实际代码的方法呢？
Unlike some developers who are always working on the same type of codebase, I don’t always know what my project directory structure will look like, but I know for sure that documentation is always appropriate.
与某些总是使用相同类型的代码库的开发人员不同，我并不总是知道我的项目目录结构是什么样子，但是我确定文档始终是合适的。
These days, the README is my first commit to any new project repository. By committing to put meaningful content in the README at the beginning of a project, I now have a place to capture everything I learn about the project as I learn it.
这些天，自述文件是我对任何新项目存储库的第一个承诺。 通过在项目开始时承诺将有意义的内容放入自述文件中，我现在有一个地方可以捕获我在学习项目时所学到的一切。
And, I’m not just talking about an empty README file so that git add has something to work with. I mean a solid first stab at real, meaningful documentation. I capture everything I know about the project and list every task I can think of. It serves as an ongoing means of reinforcing my understanding of the project and deliverables.
而且，我不仅在谈论一个空的README文件，以便git add可以使用。 我的意思是扎实，有意义的文档的第一手资料。 我捕获了有关该项目的所有知识，并列出了我能想到的每个任务。 它是不断加深我对项目和可交付成果的理解的一种手段。
As a general guideline, here are some easy things to consider including in your first README commit, in no particular order:
作为一般准则，以下是一些容易考虑的事项，包括在您的第一次README提交中的顺序(不分先后顺序)：
Dates: Any important dates for this project, such as start date, delivery deadline, or other important milestone dates.
日期 ：此项目的任何重要日期，例如开始日期，交付截止日期或其他重要的里程碑日期。
Author: This is you! At a minimum, include your name, company (if applicable), and email address.
作者 ：这就是你！ 至少要包括您的姓名，公司(如果适用)和电子邮件地址。
Reference Info: Any relevant project links such as issue lists, background documentation, or reference materials for any newcomer to the project.
参考信息：任何相关项目链接，例如问题列表，背景文档或项目新手的参考资料。
Purpose/goals: Why is this thing a project? What is the objective and what are the goals by which success can be measured?
目的/目标 ：为什么这是一个项目？ 衡量成功的目标是什么？目标是什么？
FAQ: Often an afterthought, FAQs represent some of the most important things to document. List as many as come to mind and then grow this list as new ones arise.
常见问题解答 ：通常，这是事后才想到的，它代表了一些最重要的文档。 列出尽可能多的内容，然后随着新内容的出现而增加。
Conventions: Less common, but any unique conventions that others may need to understand before digging in.
约定 ：不太常见，但在深入之前可能需要其他人理解的任何独特约定。
License information: This will likely accompany a real LICENSE file that contains the nitty gritty details, but it never hurts to reiterate the usage restrictions on the intellectual property contained in the repository.
许可证信息 ：这可能会包含一个真实的LICENSE文件 ，其中包含实质性的详细信息，但是重申存储库中包含的知识产权的使用限制不会有任何伤害。
Todos: An ongoing list of things that need to be completed for this project to be a success.
Todos ：要成功完成此项目，需要完成的工作清单。
奖励：我可以使用Markdown，Markdown很棒。 (Bonus: I get to use Markdown, and Markdown is awesome.)
The general convention for README documentation is Markdown. If you’ve never used Markdown, I highly recommend learning it. Markdown is a very easy way to transform your plain text files into nicely formatted documentation. Armed with only your text editor and a handful of new syntax conventions you can create very impressive documents without ever opening MS Word or Google Docs. Exporting HTML or PDF is also very easy.
README文档的常规约定是Markdown 。 如果您从未使用过Markdown，我强烈建议您学习它。 Markdown是将纯文本文件转换为格式正确的文档的一种非常简单的方法。 仅使用文本编辑器和一些新的语法约定，您就可以创建非常出色的文档，而无需打开MS Word或Google Docs。 导出HTML或PDF也非常容易。
Markdown has some really cool features. All the essentials are there: Tables, bulleted lists, hyperlinks, inline images, anchors and bookmarks, text formatting, and even more complex things like flowcharts and diagrams. Remember that Todo list I mentioned earlier? You can present those as checkboxes and then check them off as you complete them.
Markdown具有一些非常酷的功能。 所有必需品都在这里：表格，项目符号列表，超链接，嵌入式图像，锚点和书签，文本格式，以及甚至更复杂的东西，例如流程图和图表。 还记得我之前提到的待办事项清单吗？ 您可以将它们显示为复选框，然后在完成时将其选中。
I’ve just scratched the surface of the capabilities of Markdown. Here are several great references to check out that will give you a much better idea what you can accomplish:
我刚刚介绍了Markdown的功能。 这里有一些很棒的参考资料可以帮助您更好地了解可以完成的工作：
Markdown Tutorial: https://www.markdowntutorial.com
Markdown教程 ： https : //www.markdowntutorial.com
GitHub Markdown Guide: https://guides.github.com/pdfs/markdown-cheatsheet-online.pdf
GitHub Markdown指南 ： https : //guides.github.com/pdfs/markdown-cheatsheet-online.pdf
Mastering Markdown: https://guides.github.com/features/mastering-markdown/
精通Markdown ： https : //guides.github.com/features/mastering-markdown/
Markdown Guide: https://www.markdownguide.org
降价指南 ： https : //www.markdownguide.org
Visual Studio Code is my text editor of choice, and there are some great extensions that support Markdown. My personal favorite is Markdown All In One.
Visual Studio Code是我选择的文本编辑器，并且有一些很棒的扩展支持Markdown。 我个人最喜欢的是Markdown All in One 。
As of the time of this writing, it’s the most downloaded and is actively maintained. Among other features, it offers real-time preview and intuitive keyboard shortcuts. Other Visual Studio Code extensions offering similar functionality can be found here.
截至撰写本文时，它是下载次数最多并得到积极维护的工具。 除其他功能外，它还提供实时预览和直观的键盘快捷键。 提供类似功能的其他Visual Studio Code扩展可以在这里找到。
结论 (Conclusion)
I’m sure you’ve been there before. Looking at code that you’re 99% sure you’ve never seen before, yet your name is on it as the author. Things always have a way of coming back around. Always. Long after the project is over, it’s very likely that the documentation you create will be as much a part of your legacy as the source code itself.
我确定你以前去过那里。 查看您99％肯定从未见过的代码，但您的名字是作者。 事情总是有回头路的方法。 总是。 在项目结束很长时间之后，您创建的文档很可能会与源代码本身一样成为遗留部分。
If you’re looking to up your documentation game, I highly recommend starting your next project with a README. This approach has really helped me to strengthen my deliverables and level up my own contributions to projects. Even if you try it and don’t like it, at least maybe you’ll end up with better Markdown skills. Even that makes it worth the effort.
如果您正在寻找文档游戏，我强烈建议您使用自述文件开始下一个项目。 这种方法确实帮助我增强了可交付成果并提高了自己对项目的贡献。 即使您尝试它并且不喜欢它，至少也许您将获得更好的Markdown技能。 即使这样做也值得付出努力。
Still not convinced? Leave me a comment below and let’s start a dialogue!
还是不服气？ 在下面给我留言，让我们开始对话！
hbuilder自述文件
701
被折叠的 条评论
为什么被折叠?
到【灌水乐园】发言
