From a2ec8062a0ae9c048f4a30fa8a414b9c2ddf6e8c Mon Sep 17 00:00:00 2001 From: Xingyu Wang Date: Tue, 6 Oct 2020 22:24:52 +0800 Subject: [PATCH 1/2] PRF @geekpi --- ...self when writing project documentation.md | 40 +++++++++---------- 1 file changed, 20 insertions(+), 20 deletions(-) diff --git a/translated/tech/20200925 5 questions to ask yourself when writing project documentation.md b/translated/tech/20200925 5 questions to ask yourself when writing project documentation.md index bbf3b907cc..ee3dccb2db 100644 --- a/translated/tech/20200925 5 questions to ask yourself when writing project documentation.md +++ b/translated/tech/20200925 5 questions to ask yourself when writing project documentation.md @@ -1,52 +1,52 @@ [#]: collector: (lujun9972) [#]: translator: (geekpi) -[#]: reviewer: ( ) +[#]: reviewer: (wxy) [#]: publisher: ( ) [#]: url: ( ) [#]: subject: (5 questions to ask yourself when writing project documentation) [#]: via: (https://opensource.com/article/20/9/project-documentation) [#]: author: (Alexei Leontief https://opensource.com/users/alexeileontief) -编写项目文档时要问自己 5 个问题 +编写项目文档时要问自己的 5 个问题 ====== -使用一些有效沟通的基本原则可以帮助你创建与你的品牌一致的，编写良好，内容丰富的项目文档。 + +> 使用有效沟通的一些基本原则可以帮助你创建与你的品牌一致的、编写良好、内容丰富的项目文档。 + ![A person writing.][1] -在开始另一个开源项目文档的实际写作部分之前，甚至在采访专家之前，最好回答一些有关新文档的高级问题。 +在开始实际撰写又一个开源项目的文档之前，甚至在采访专家之前，最好回答一些有关新文档的高级问题。 -著名的传播理论家 Harold Lasswell 在他 1948 年的文章《社会中的传播结构和功能》（_The Structure and Function of Communication in Society_）中写道： +著名的传播理论家 Harold Lasswell 在他 1948 年的文章《社会中的传播结构和功能The Structure and Function of Communication in Society》中写道： -> （一个）描述沟通行为的方便方法是回答以下问题： +> （一种）描述沟通行为的方便方法是回答以下问题： > > * 谁 > * 说什么 > * 在哪个渠道 > * 对谁 > * 有什么效果？ -> +作为一名技术交流者，你可以运用 Lasswell 的理论，回答关于你文档的类似问题，以更好地传达你的信息，达到预期的效果。 -作为一名技术沟通者，你可以运用 Lasswell 的理论，回答关于你文档的类似问题，以更好地传达你的信息，达到预期的效果。 +### 谁：谁是文档的所有者？ -### 谁—谁是文档的所有者？ +或者说，文档背后是什么公司？它想向受众传达什么品牌形象？这个问题的答案将极大地影响你的写作风格。公司可能有自己的风格指南，或者至少有正式的使命声明，在这种情况下，你应该从这开始。 -或者说，文档背后是什么公司？它想向受众传达什么品牌形象？这个问题的答案将大大影响你的写作风格。公司也可能有自己的风格指南，或者至少有正式的使命声明，在这种情况下，你应该从这开始。 +如果公司刚刚起步，你可以向文件的主人提出上述问题。作为作者，将你为公司创造的声音和角色与你自己的世界观和信念结合起来是很重要的。这将使你的写作看起来更自然，而不像公司的行话。 -如果公司刚刚起步，你可以向文件的主人提出上述问题。作为作者，将你为公司创造的声音和角色与你自己的世界观和信仰结合起来是很重要的。这将使你的写作看起来更自然，而不像公司的行话。 +### 说什么：文件类型是什么？ -### 说什么—文件类型是什么？ +你需要传达什么信息？它是什么类型的文档：用户指南、API 参考、发布说明等？许多文档类型有模板或普遍认可的结构，这些结构为你提供一个开始的地方，并帮助确保包括所有必要的信息。 -你需要传达什么信息？它是什么类型的文档：用户指南、API 参考、发布说明等？许多文档类型将有模板或普遍认可的结构，它将让你从这开始，并帮助确保包括所有必要的信息。 - -### 在哪个渠道—文档的格式是什么？ +### 在哪个渠道：文档的格式是什么？ 对于技术文档，沟通的渠道通常会告诉你文档的最终格式，也就是 PDF、HTML、文本文件等。这很可能也决定了你应该使用什么工具来编写你的文档。 -### 对谁—目标受众是谁？ +### 对谁：目标受众是谁？ -谁会阅读这份文档？他们的知识水平如何？他们的工作职责和主要挑战是什么？这些问题将帮助你确定你应该覆盖什么，是否应该进入细节，是否可以使用任何特定的术语，等等。在某些情况下，这些问题的答案甚至可以影响你使用的语法的复杂性。 +谁会阅读这份文档？他们的知识水平如何？他们的工作职责和主要挑战是什么？这些问题将帮助你确定你应该覆盖什么内容，是否应该应该涉及细节，是否可以使用特定的术语，等等。在某些情况下，这些问题的答案甚至可以影响你使用的语法的复杂性。 -### 有什么效果-文档的目的是什么？ +### 有什么效果：文档的目的是什么？ 在这里，你应该定义这个文档要为它的潜在读者解决什么问题，或者它应该为他们回答什么问题。例如，你的文档的目的可以是教你的客户如何使用你的产品。 @@ -56,7 +56,7 @@ ### 总结 -上面的问题旨在帮助你形成有效沟通的基础，并确保你的文件涵盖了所有应该涵盖的内容。你可以把它们分解成你自己的问题清单，并把它们放在身边，以便在你有文件要创建的时候使用。当你面对空白页时，这份清单也可能会派上用场。希望它能激发你的灵感，帮助你产生想法。 +上面的问题旨在帮助你形成有效沟通的基础，并确保你的文件涵盖了所有应该涵盖的内容。你可以把它们分解成你自己的问题清单，并把它们放在身边，以便在你有文件要创建的时候使用。当你面对空白页无从着笔时，这份清单也可能会派上用场。希望它能激发你的灵感，帮助你产生想法。 -------------------------------------------------------------------------------- @@ -65,7 +65,7 @@ via: https://opensource.com/article/20/9/project-documentation 作者：[Alexei Leontief][a] 选题：[lujun9972][b] 译者：[geekpi](https://github.com/geekpi) -校对：[校对者ID](https://github.com/校对者ID) +校对：[wxy](https://github.com/wxy) 本文由 [LCTT](https://github.com/LCTT/TranslateProject) 原创编译，[Linux中国](https://linux.cn/) 荣誉推出 From 8bc41121807f689eca3bfb74792099a761a473e9 Mon Sep 17 00:00:00 2001 From: Xingyu Wang Date: Tue, 6 Oct 2020 22:32:58 +0800 Subject: [PATCH 2/2] PUB @geekpi https://linux.cn/article-12691-1.html --- ...ns to ask yourself when writing project documentation.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) rename {translated/tech => published}/20200925 5 questions to ask yourself when writing project documentation.md (96%) diff --git a/translated/tech/20200925 5 questions to ask yourself when writing project documentation.md b/published/20200925 5 questions to ask yourself when writing project documentation.md similarity index 96% rename from translated/tech/20200925 5 questions to ask yourself when writing project documentation.md rename to published/20200925 5 questions to ask yourself when writing project documentation.md index ee3dccb2db..3b59da6ca5 100644 --- a/translated/tech/20200925 5 questions to ask yourself when writing project documentation.md +++ b/published/20200925 5 questions to ask yourself when writing project documentation.md @@ -1,8 +1,8 @@ [#]: collector: (lujun9972) [#]: translator: (geekpi) [#]: reviewer: (wxy) -[#]: publisher: ( ) -[#]: url: ( ) +[#]: publisher: (wxy) +[#]: url: (https://linux.cn/article-12691-1.html) [#]: subject: (5 questions to ask yourself when writing project documentation) [#]: via: (https://opensource.com/article/20/9/project-documentation) [#]: author: (Alexei Leontief https://opensource.com/users/alexeileontief) @@ -12,7 +12,7 @@ > 使用有效沟通的一些基本原则可以帮助你创建与你的品牌一致的、编写良好、内容丰富的项目文档。 -![A person writing.][1] +![](https://img.linux.net.cn/data/attachment/album/202010/06/223150omjnutjpml8inc9n.jpg) 在开始实际撰写又一个开源项目的文档之前，甚至在采访专家之前，最好回答一些有关新文档的高级问题。