Some thoughts and guidelines on writing issues, tickets, pull request descriptions, release notes and documentation in general.

一般而言，有关编写问题，票证，请求说明，发行说明和文档的一些想法和准则。

I’ve always had an interest in many things related to software development and design. And another field I’ve developed interest since moving to another country, where they speak a different language from my own and obviously have a different culture too, is communication.

我一直对与软件开发和设计有关的许多事情感兴趣。 自从搬到另一个国家/地区以来，我一直对另一个领域感兴趣，那就是交流。

Communicating is obviously relevant for every aspect of our daily life but this article will focus on the professional environment, specially software development, since it’s kind of “my trade”.

交流显然与我们日常生活的方方面面都息息相关，但本文将重点关注专业环境，尤其是软件开发，因为这是“我的交易”。

沟通的重要性 (The Importance of Communication)

Throughout my career I’ve learned that it doesn’t matter what you work on, it’s vital to be able to communicate to other people how and why the things you’re creating work the way they work.

在我的整个职业生涯中，我已经了解到您从事的工作并不重要，能够与其他人交流您创建的事物如何以及为什么以他们的工作方式运作至关重要。

Seriously, whatever it is. If people can’t understand it, it’s probably doomed to be shelved or discarded. Be it an “exciting” new product feature or “boring” documentation for some company process.

说真的，不管是什么。 如果人们听不懂，它可能注定要被搁置或丢弃。 它是某些公司流程的“令人兴奋”的新产品功能还是“无聊的”文档。

Improving your communication skills will open many doors in your professional career (and also in life). Which brings me to the next point.

改善沟通技巧将为您的职业生涯(以及生活)打开许多大门。 这将我带到下一点。

使自己变得可有可无 (Making yourself dispensable)

It’s very common in software development to be afraid of not being seen as an “indispensable” employee by our employers. This sometimes leads people into making some bad decisions, that although it renders them effectively indispensable in the short term, hinders them in their professional development in the long term.

在软件开发中很常见，就是害怕被我们的雇主视为“不可缺少的”雇员。 有时这会导致人们做出一些错误的决定，尽管这使他们在短期内实际上是必不可少的，但从长远来看却阻碍了他们的专业发展。

One of these bad decisions is holding code ransom, it’s specially (in)famous in the video game industry, this is a practice where you make the portions of code you work on in any given project so difficult to understand or maintain that they “can’t get rid of you” because you’re the only one that can work on them.

这些错误的决定之一就是持有代码赎金，这在视频游戏行业中是众所周知的，这是一种做法，您要使在任何给定项目中工作的代码部分变得难以理解或维护，以至于他们“ “不要摆脱你”，因为您是唯一可以对付他们的人。

This will most likely backfire in many cases. And worse, it’ll be detrimental to your career and even when it does work you’ll now be chained to that unmaintainable code forever*.

在许多情况下，这很可能适得其反。 更糟糕的是，这将对您的职业有害，即使它确实起作用了，您现在也将永远被束缚在那个无法维护的代码上*。

A better option is going in the exact opposite direction, setting up everything you do in a way that’s easy for other developers and ideally also non-technical people to understand.

更好的选择是朝相反的方向前进，以其他开发人员以及理想情况下非技术人员也易于理解的方式设置您所做的所有事情。

This is not something I came up with by myself, I just learned it somewhere and internalised it over time, so much it turned into one of my main working principles:

这不是我自己想到的，我只是在某个地方学习并将其内部化，随着时间的流逝，它变成了我的主要工作原则之一：

“Make yourself dispensable”

“让自己变得可有可无”

When you work this way, building software that’s just easy to be handed over, you’re setting yourself up to be able to take on bigger, more exciting projects in the future. All of this without being “hindered” by existing projects you’re involved in, since it will be easy for you to delegate or transfer ownership of them.

当您以这种方式工作时，构建易于交付的软件，就意味着您自己可以在将来承担更大，更令人兴奋的项目。 所有这些都不会受到您所参与的现有项目的“阻碍”，因为您可以轻松地委派或转让它们的所有权。

As an added benefit, were you to leave the company or be hit by a bus or something, your work (and your legacy, if you feel inclined to see it that way) won’t run the risk of being put in a drawer or even worse, binned.

另外一个好处是，如果您离开公司或被公交车或其他东西撞到，您的工作(以及您的遗产，如果您倾向于这样看的话)不会冒被放在抽屉里的风险。更糟的是，装箱。

并非所有开发人员提示都与代码有关 (Not all developer tips are related to code)

So, aside from the usual code-related tips to be a better developer, keep in mind what I said at the beginning:

因此，除了成为一名更好的开发人员的常规代码相关技巧之外，请记住我在开始时所说的话：

A very important aspect of making yourself dispensable is communicating effectively with all members of the team, and often with users as well.

使自己变得可有可无的一个非常重要的方面是与团队的所有成员以及经常与用户进行有效的沟通。

So without further ado, let’s now talk about that. But not before giving you some bonus top quality code-related developer tips:

因此，事不宜迟，让我们现在谈谈。 但是在为您提供一些与代码相关的高质量顶级开发人员技巧之前，请注意以下几点：

• “You should write your code so it reads like a book”

  “您应该编写代码，使其读起来像本书”

• “Always make sure to name things in a meaningful way” (Something developers struggle with. Yes, people who write single letter variables, I’m specially looking at you!)

  “总是确保以有意义的方式命名事物” (某些开发人员会为此感到困惑。是的，写单字母变量的人，我特别看着你！)

在技​​术环境中进行有效沟通的准则 (Guidelines for Communicating Effectively in a Technical Environment)

First of all, there’s not a universal set of rules for technical documents. They have different scopes, audiences, structures, etc. Writing tutorials or documenting processes is different from writing a ticket or documenting a feature, and so on. They also vary by company.

首先，技术文档没有一套通用的规则。 它们具有不同的范围，受众，结构等。编写教程或记录过程与编写票证或记录功能不同，依此类推。 它们也因公司而异。

Nevertheless, there are some aspects that’ll always be good to keep in mind:

尽管如此，仍然需要牢记一些方面：

简明扼要 (Be concise)

You’re aiming to write the shortest, practical, useful and self-contained document possible.

您的目标是编写尽可能短，实用，有用和独立的文档。

Too long and no one will read it. You’ve wasted all that time writing it all for nothing, maybe you went the extra mile to add lots of useful contextual information and now it’ll be forgotten in some dark corner of a git repo.

时间太长，没人会读。 您浪费了所有的时间，一无所有地编写了所有内容，也许您付出了额外的努力来添加许多有用的上下文信息，但是现在它已经在git repo的某个黑暗角落被遗忘了。

Too short and no one will read it. Well at least this time you didn’t waste much time on it, but it’s useless, no one will understand anything and they’ll be interrupting you to ask you silly questions all the time because there’s no decent documentation for your feature/product.

太短了，没人会读。 好吧，至少这次您没有花太多时间，但是它没有用，没有人会理解任何东西，并且因为您的功能/产品没有合适的文档，所以他们会一直打扰您，向您提出愚蠢的问题。

How do you know if it’s too short or too long? Experience and… surprise surprise! communication with other humans to get feedback on it. Communication goes both ways, even for documentation.

您怎么知道它太短还是太长？ 经验和…惊喜惊喜！ 与其他人进行交流以获得反馈。 交流是双向的，即使是文档也是如此。

解释事物的原因 (Explain the Why of things)

The extent of how much you’ll explain will vary. In some cases you’ll want to extend, to relay some important knowledge, like in a tutorial or a documenting a feature.

您要解释的程度会有所不同。 在某些情况下，您需要扩展以传达一些重要的知识，例如在教程或功能文档中。

In other cases it’ll be better to provide just some basic context and add links the reader can follow to learn more about the subject being explained.

在其他情况下，最好只提供一些基本上下文并添加读者可以跟随以了解有关所解释主题的链接。

This is something I find very important and is frequently overlooked. Every mind is different and each of us stores knowledge in our head in a different way (cue Mental Models).

我觉得这很重要，并且经常被忽略。 每个人的思维都不尽相同，我们每个人以不同的方式将知识存储在我们的脑海中(提示心理模型)。

We also have a tendency to not ask questions, just to avoid looking dumb in front of others (A perceived victory that only stays with us until we get stuck trying to exit the Zoom meeting, saying “bye” repeatedly, in panic, until we finally find the “Leave Meeting” button).

我们也倾向于不问问题，只是为了避免在别人面前显得愚蠢(感知到的胜利只会一直伴随着我们，直到我们陷于试图退出Zoom会议的过程中，反复地“再见”，惊慌失措，直到我们最后找到“离开会议”按钮)。

By providing context on the components/processes you’re documenting you improve the reader’s chances of getting a more complete idea of the subject in general. Potentially helping catch errors you made or proposing improvements to your documentation (or even the product) as well.

通过提供要记录的组件/过程的上下文，可以提高读者获得有关该主题的更完整概念的机会。 潜在地帮助发现您所犯的错误，或者还建议对文档(甚至产品)进行改进。

When writing tickets/issues where the context is commonly known there’s no need to go into much detail, specially if they are sub-tickets or are linked in another way to another ticket where the context has been explained before.

在通常已知上下文的情况下编写票证/问题时，无需进行过多详细说明，尤其是当它们是子票证或以其他方式链接到之前已说明上下文的另一票证时。

So you’ll have to balance explaining enough with a DRY approach. Which brings us to the next point.

因此，您必须通过DRY方法来平衡说明。 这将我们带到了下一点。

不要重新发明轮子 (Don’t reinvent the wheel)

In cases where you are referring to other sections of your own documentation try to not repeat content, as you’ll be extending the documentation surface area you’ll need to maintain. It will also run the risk of getting stale when the content of the section you’re paraphrasing gets updated.

如果您要参考自己文档的其他部分，请不要重复内容，因为这将扩展您需要维护的文档表面积。 当您要解释的部分的内容更新时，也可能会导致过时。

There’s a gotcha with this, sometimes you will repeat yourself but because you’re being more specific on some aspects. For example, when writing the description for a PR you’ve created, to solve ticket A-123.

这有一个陷阱，有时您会重复一遍，但是因为您在某些方面更加具体。 例如，为已创建的PR编写描述时，将解决票证A-123。

In the ticket you’ll generally write what needs to be done in plain english. But then the PR description will need some more technical details. Here’s a very simple example, you won’t write something like this in real life but illustrates the point:

在票证中，您通常会用简单的英语写下需要做的事情。 但是，PR说明将需要更多技术细节。 这是一个非常简单的示例，您在现实生活中不会写这样的东西，但可以说明这一点：

Ticket: As a platform user I want to be able to click on a button to add a product to my basket. So that when I decide to check out the product will be in my basket, even if I’m using a different browser.

票证：作为平台用户，我希望能够单击一个按钮将产品添加到我的购物篮中。 这样，即使我使用其他浏览器，当我决定签出该产品时，仍将在我的购物篮中。

PR Description: Adds an “Add to basket” button. This button dispatches an action that triggers a POST request to the API to add the product to the user’s basket and if successful updates local state. Library X and Y have been added to handle HTTP requests and state respectively.

PR说明：添加一个“添加到购物篮”按钮。 此按钮向API调度触发POST请求的操作，以将产品添加到用户的购物篮中，如果成功更新了本地状态。 库X和Y已添加，分别用于处理HTTP请求和状态。

避免技术术语 (Avoid technical jargon)

Even though it’s technical documentation you should try to always write in a simple and clear way when possible. The idea is to lower the cognitive barrier for readers. You’re relaying knowledge, not doing your best impression of The Architect in “The Matrix Reloaded”.

即使是技术文档，您也应尽可能尝试以简单明了的方式编写。 这个想法是为了降低读者的认知障碍。 您是在传递知识，而不是在“ The Matrix Reloaded”中没有对The Architect产生最好的印象。

使用直观一致的结构 (Use an intuitive and consistent structure)

You could write the best documentation ever in regards to substance, but if it’s a mess with no logic ordering of sections it’s worthless. Nobody will read it.

您可以写出有史以来最好的有关实质性的文档，但是如果这是一团糟，没有对各部分进行逻辑排序，那将毫无用处。 没有人会读。

This is not something I’m making up, it’s based on psychology and even though documentation is “just text” it’s also affected by what’s called The Gestalt Principles because it’s humans who consume it, and we love ourselves some pattern matching!

这不是我要编造的东西，它是基于心理学的，即使文档只是“文本”，它也受到格式塔原理的影响，因为它是人类消耗的，我们也喜欢模式匹配！

Being consistent in how you structure your documentation will make it easier to read and also to navigate.

保持文档结构的一致性将使其更易于阅读和浏览。

Try and group similar sections together as much as logically possible. If section A is related to section B don’t have them be in opposite ends of your document. Also, don’t be afraid of using nested sections when applicable.

尝试在逻辑上尽可能将相似的部分组合在一起。 如果A节与B节相关，则不要将它们放在文档的相反两端。 同样，在适用时不要害怕使用嵌套部分。

If you have trouble figuring out how to structure your documentation, the approach of grouping by layer and by feature also applies to documentation.

如果您在确定如何组织文档方面遇到困难，则按层和按功能分组的方法也适用于文档。

使用空格对您有利 (Use spacing in your favour)

Don’t just dump all the information in plain text and leave it. If the tool you’re using provides rich text features, like headings, lists, quotes, etc, use them in your favour. This makes it easier for other people to scan and read your document without being overwhelmed.

不要只将所有信息以纯文本格式转储并保留。 如果您使用的工具提供了丰富的文本功能，例如标题，列表，引号等，请使用它们。 这使其他人可以更轻松地扫描和阅读您的文档而不会感到不知所措。

Adding blank spaces here and there sometimes doesn’t hurt either, specially if you don’t have rich text features available. Just remember to be consistent with it.

有时到处添加空格也不会有任何问题，特别是如果您没有可用的富文本功能。 请记住要与之保持一致。

格式化代码段和命令 (Format code snippets and commands)

Following on the usage of rich text features, this is not limited to headings and lists. Usually you can also format text as “code” or at least changing the font to monospace.

在使用富文本功能之后，这不仅限于标题和列表。 通常，您还可以将文本设置为“代码”格式，或者至少将字体更改为等宽字体。

This makes it easier for users to parse your document, as well as being able to copy and paste that content and use it directly. Avoiding typos and the classic formatting issue where text editors turn double-quotes into angled double-quotes.

这使用户可以更轻松地解析您的文档，以及能够复制和粘贴该内容并直接使用它。 避免输入错误和传统的格式设置问题，在这种情况下，文本编辑器会将双引号变成有角度的双引号。

Most commands in documentation follow some kind of Extended Backus-Naur Form, It’s a common syntax convention. An example of it is commands with optional arguments, where those arguments that are optional are wrapped in square brackets like:

文档中的大多数命令都遵循某种扩展Backus-Naur形式，这是一种常见的语法约定。 它的一个示例是带有可选参数的命令，其中那些可选参数包装在方括号中，例如：

$ command_that_does_something [-optional-argument]

$ command_that_does_something [-optional-argument]

The $ symbol is another convention to denote this is a terminal command, it’s been falling out of favour recently. For better examples take a look at git’s documentation or npm’s.

$符号是另一种约定，表示这是一个终端命令，最近一直不受欢迎。 有关更好的示例，请查看git的文档或npm的文档。

使用主动语音 (Use Active voice)

This is one of those obvious but difficult to grasp and there’s also kind of a moving goal posts situation. In the sense that you don’t need to be so strict with it aside from documents like tutorials and guides for example. Where the reader is the subject, and it needs to be clear it’s them who is performing the action, and you’re listing actions they need to take.

这是显而易见但很难掌握的一种，还有一种动态的目标发布情况。 从某种意义上说，除了教程和指南之类的文档之外，您不需要严格要求它。 读者是主题的主体，需要明确的是是谁在执行操作，而您列出了他们需要执行的操作。

Examples from Google’s developer documentation style guide:

Google开发者文档样式指南中的示例：

Wrong: The service is queried, and an acknowledgment is sent.

错误：查询了服务，并发送了确认。

Correct: Send a query to the service. The server sends an acknowledgment.

正确：向服务发送查询。 服务器发送确认。

知道什么时候不要过度记录 (Know when not to over-document)

This one applies to shorter and actionable documents like user stories, bug reports, etc.

此文档适用于较短且可操作的文档，例如用户案例，错误报告等。

When you’re documenting something that’s very specific and contained you can probably get away with raising a small ticket and referencing it somewhere relevant like in a “parent” ticket or a Pull Request.

当您记录非常具体且包含在内的内容时，您可能可以举起一张小票，并在诸如“父”票或“拉取请求”之类的相关地方引用它，从而摆脱困境。

Another example is creating (or updating) a README file instead of creating a Word document or adding a whole new section in your organisation’s documentation site.

另一个示例是创建(或更新)自述文件，而不是创建Word文档或在组织的文档站点中添加一个全新的部分。

Opting for smaller documents like this could provide useful in the future as you create something like a paper trail, making it easier for you to track small changes and why they were made.

选择类似的较小文档可能会在以后创建纸迹时提供有用的信息，从而使您更容易跟踪较小的更改以及进行更改的原因。

最后说明 (Final note)

These are just some concepts and practices I find very useful and try to always apply at work.

这些只是我发现非常有用的一些概念和实践，它们总是在工作中应用。

By no means I think these points I’ve exposed here are all there is, this is a very subjective subject and even inside big companies it’s difficult for teams to agree on a single set of rules for these things. Most guides you’ll read across the web emphasise they’re just that, guides, not rules.

我绝不认为我在这里暴露的这些要点是全部，这是一个非常主观的主题，即使在大公司内部，团队也很难就这些事情达成一套统一的规则。 您在网络上阅读的大多数指南都强调它们仅仅是指南，而不是规则。

I’m pretty sure I’ll keep iterating on this and adding more as I keep moving forward in my career.

我很确定我会不断对此进行迭代，并在我继续前进的过程中增加更多。

我在研究撰写这篇文章时发现了很棒的内容 (Great content I found while doing my research to write this post)

A very interesting post by Geoffrey Teale, it’s focused on documenting at code level.( i.e. block comments in code and the like) and has some interesting points about the scalability of a development team.

Geoffrey Teale的一篇非常有趣的文章，专注于代码级别的文档编制(即，代码中的块注释等)，并且有关开发团队的可伸缩性有一些有趣的观点。

It’s in a way looking at the same problem, just from a different perspective, and reaching the same solution: documenting knowledge.

它以一种不同的视角看待相同的问题，并达到相同的解决方案：记录知识。

Coding etiquette is a whole different world that I might write about in the future. It’s something that also varies a lot depending on the language, company, etc.

编码礼节是一个完全不同的世界，我将来可能会写。 根据语言，公司等的不同，差异也很大。

A really good post by Angela Zhang on how to write software design docs, much more technical than this post. With really good points like the Skeptic Test and the Vacation Test.

Angela Zhang撰写的关于如何编写软件设计文档的非常好的文章，比这篇文章更具技术性。 具有怀疑测试和假期测试之类的优点。

A great post by Stephen Whitworth, focusing on proposals, or RFCs (Request For Comments) as they’re known in open source, their importance and the benefits they bring over just starting to code directly.

Stephen Whitworth撰写的精彩文章，重点讨论了开源中众所周知的提案或RFC(征求意见稿)，其重要性以及直接开始进行编码所带来的好处。

DigitalOcean’s Technical Writing guidelines. This is more focused on guides/tutorials and they even have templates available for you to use.

DigitalOcean的技术写作指南。 这更侧重于指南/教程，甚至它们都有可供您使用的模板。

Google’s developer documentation style guide. This is more extensive and general, focuses more in language, grammar, punctuation and how to make references to code.

Google的开发人员文档样式指南。 这是更广泛，更笼统的内容，重点是语言，语法，标点符号以及如何引用代码。

Industrial Empathy’s post is very useful and focuses more on planning and structuring a design doc.

Industrial Empathy的帖子非常有用，并且更多地侧重于规划和构造设计文档。

A design doc is a document that’s initially a project proposal (design, planning, scope, constraints, etc) and evolves as the project is implemented and eventually deployed.

设计文档是一个文档，最初是项目建议书(设计，计划，范围，约束等)，并随着项目的实施和最终部署而发展。

It even dedicates a portion of the post to when NOT to write a design doc.

它甚至将帖子的一部分专门用于何时不编写设计文档。

Microsoft’s style guide I think is very useful specially for short documents. Provides a very robust checklist you can follow to craft very solid templates for things like tickets, pull requests, release notes, etc.

我认为Microsoft的样式指南特别适用于简短文档。 提供了一个非常强大的清单，您可以遵循该清单来为票证，提取请求，发行说明等内容设计非常坚实的模板。

Planio’s post is also very helpful and provides a very concise list of 5 steps to follow to make sure you’re writing great documentation in general.

Planio的帖子也非常有帮助，并提供了一个非常简洁的清单，该清单包含5个步骤，以确保您总体上写出了出色的文档。