mirror of
https://github.com/LCTT/TranslateProject.git
synced 2024-12-29 21:41:00 +08:00
76 lines
4.5 KiB
Markdown
76 lines
4.5 KiB
Markdown
[#]: collector: (lujun9972)
|
||
[#]: translator: (geekpi)
|
||
[#]: reviewer: (wxy)
|
||
[#]: 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)
|
||
|
||
编写项目文档时要问自己的 5 个问题
|
||
======
|
||
|
||
> 使用有效沟通的一些基本原则可以帮助你创建与你的品牌一致的、编写良好、内容丰富的项目文档。
|
||
|
||
|
||
|
||
在开始实际撰写又一个开源项目的文档之前，甚至在采访专家之前，最好回答一些有关新文档的高级问题。
|
||
|
||
著名的传播理论家 Harold Lasswell 在他 1948 年的文章《<ruby>社会中的传播结构和功能<rt>The Structure and Function of Communication in Society</rt></ruby>》中写道：
|
||
|
||
> （一种）描述沟通行为的方便方法是回答以下问题：
|
||
>
|
||
> * 谁
|
||
> * 说什么
|
||
> * 在哪个渠道
|
||
> * 对谁
|
||
> * 有什么效果？
|
||
|
||
作为一名技术交流者，你可以运用 Lasswell 的理论，回答关于你文档的类似问题，以更好地传达你的信息，达到预期的效果。
|
||
|
||
### 谁：谁是文档的所有者？
|
||
|
||
或者说，文档背后是什么公司？它想向受众传达什么品牌形象？这个问题的答案将极大地影响你的写作风格。公司可能有自己的风格指南，或者至少有正式的使命声明，在这种情况下，你应该从这开始。
|
||
|
||
如果公司刚刚起步，你可以向文件的主人提出上述问题。作为作者，将你为公司创造的声音和角色与你自己的世界观和信念结合起来是很重要的。这将使你的写作看起来更自然，而不像公司的行话。
|
||
|
||
### 说什么：文件类型是什么？
|
||
|
||
你需要传达什么信息？它是什么类型的文档：用户指南、API 参考、发布说明等？许多文档类型有模板或普遍认可的结构，这些结构为你提供一个开始的地方，并帮助确保包括所有必要的信息。
|
||
|
||
### 在哪个渠道：文档的格式是什么？
|
||
|
||
对于技术文档，沟通的渠道通常会告诉你文档的最终格式，也就是 PDF、HTML、文本文件等。这很可能也决定了你应该使用什么工具来编写你的文档。
|
||
|
||
### 对谁：目标受众是谁？
|
||
|
||
谁会阅读这份文档？他们的知识水平如何？他们的工作职责和主要挑战是什么？这些问题将帮助你确定你应该覆盖什么内容，是否应该应该涉及细节，是否可以使用特定的术语，等等。在某些情况下，这些问题的答案甚至可以影响你使用的语法的复杂性。
|
||
|
||
### 有什么效果：文档的目的是什么？
|
||
|
||
在这里，你应该定义这个文档要为它的潜在读者解决什么问题，或者它应该为他们回答什么问题。例如，你的文档的目的可以是教你的客户如何使用你的产品。
|
||
|
||
这时，你可以参考 [Divio][2] 建议的方法。根据这种方法，你可以根据文档的总体方向，将任何文档分为四种类型之一：学习、解决问题、理解或获取信息。
|
||
|
||
在这个阶段，另一个很好的问题是，这个文档要解决什么业务问题（例如，如何削减支持成本）。带着业务问题，你可能会看到你写作的一个重要角度。
|
||
|
||
### 总结
|
||
|
||
上面的问题旨在帮助你形成有效沟通的基础，并确保你的文件涵盖了所有应该涵盖的内容。你可以把它们分解成你自己的问题清单，并把它们放在身边，以便在你有文件要创建的时候使用。当你面对空白页无从着笔时，这份清单也可能会派上用场。希望它能激发你的灵感，帮助你产生想法。
|
||
|
||
--------------------------------------------------------------------------------
|
||
|
||
via: https://opensource.com/article/20/9/project-documentation
|
||
|
||
作者：[Alexei Leontief][a]
|
||
选题：[lujun9972][b]
|
||
译者：[geekpi](https://github.com/geekpi)
|
||
校对：[wxy](https://github.com/wxy)
|
||
|
||
本文由 [LCTT](https://github.com/LCTT/TranslateProject) 原创编译，[Linux中国](https://linux.cn/) 荣誉推出
|
||
|
||
[a]: https://opensource.com/users/alexeileontief
|
||
[b]: https://github.com/lujun9972
|
||
[1]: https://opensource.com/sites/default/files/styles/image-full-size/public/lead-images/rh_003784_02_os.comcareers_resume_rh1x.png?itok=S3HGxi6E (A person writing.)
|
||
[2]: https://documentation.divio.com/
|