document/TranslateProject
2
0
Fork 0
mirror of https://github.com/LCTT/TranslateProject.git synced 2025-01-13 22:30:37 +08:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #19717 from geekpi/translating

Browse Source 
translating
This commit is contained in:
geekpi 2020-09-30 08:48:26 +08:00 committed by GitHub
commit cf0291268a
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
2 changed files with 75 additions and 77 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

77
sources/tech/20200925 5 questions to ask yourself when writing project documentation.md
View File

@ -1,77 +0,0 @@
[#]: collector: (lujun9972)
[#]: translator: (geekpi)
[#]: reviewer: ( )
[#]: 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 questions to ask yourself when writing project documentation
======
Using some of the basic principles of effective communication can help
you create well-written, informative project documents that align with
your brand.
![A person writing.][1]
Before getting down to the actual writing part of documenting another one of your open source projects, and even before interviewing the experts, it's a good idea to answer some high-level questions about your new document.
Renowned communication theorist Harold Lasswell wrote in his 1948 article, _The Structure and Function of Communication in Society_:
> [A] convenient way to describe an act of communication is to answer the following questions:
>
> * Who
> * Says what
> * In which channel
> * To whom
> * With what effect?
>
As a technical communicator, you can apply Lasswell's theory and answer similar questions about your document to communicate your message better and with the desired effect.
### Who—Who is the document owner?
Or, what company is behind the document? What brand identity does it want to convey to its audience? The answer to this question will significantly influence your writing style. The company may also have its own style guide or at least a formal mission statement, in which case, you should start there.
If the company is just starting out, you may ask the questions above to the document's owner. As the writer, it's important to integrate the voice and persona you create for the company with your own worldview and beliefs. This will make your writing sound more natural and less like company jargon.
### Says what—What is the document type?
What information do you need to communicate? What type of document is it: a user guide, API reference, release notes, etc.? Many document types will have templates or generally agreed-upon structures that will give you a place to start and help ensure you include all the necessary information.
### In which channel—What is the format of the document?
With technical documents, the channel of communication often informs the final format of your doc, i.e., whether it's going to be a PDF, HTML, a text file, etc. This will, most likely, also determine the tools you should use to write your document.
### To whom—Who is the target audience?
Who will read this document? What is their level of knowledge? What are their job responsibilities and their main challenges? These questions will help you determine what you should cover, whether or not you should go into details, whether you can use any specific terms, etc. In some cases, the answers to these questions can even influence the complexity of syntax that you should use.
### With what effect—What is the purpose of the document?
This is where you should define what problem(s) this document is expected to solve for its prospective readers, or what questions it should answer for them. For example, the purpose of your document can be to teach your customers to work with your product.
At this point, you may refer to the approach suggested by [Divio][2]. According to this approach, you can assign any document one of four types, depending on the document's general orientation: learning, solving a problem, understanding, or getting information.
Another good question to ask at this stage is what business problem this document is meant to solve (for example, how to cut down support costs.) With a business problem in mind, you may see an important angle for your writing.
### Conclusion
The questions above are designed to help you form the basis for effective communication and ensure your document covers everything it should. You can break them down into your own checklist of questions and keep them around for whenever you have a document to create. This checklist may also come in handy when you become stuck, confronted with a blank page. It will hopefully inspire you and help you generate ideas.
--------------------------------------------------------------------------------
via: https://opensource.com/article/20/9/project-documentation
作者：[Alexei Leontief][a]
选题：[lujun9972][b]
译者：[译者ID](https://github.com/译者ID)
校对：[校对者ID](https://github.com/校对者ID)
本文由 [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/

75
translated/tech/20200925 5 questions to ask yourself when writing project documentation.md Normal file
View File

@ -0,0 +1,75 @@
[#]: collector: (lujun9972)
[#]: translator: (geekpi)
[#]: reviewer: ( )
[#]: 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 个问题
======
使用一些有效沟通的基本原则可以帮助你创建与你的品牌一致的，编写良好，内容丰富的项目文档。
![A person writing.][1]
在开始另一个开源项目文档的实际写作部分之前，甚至在采访专家之前，最好回答一些有关新文档的高级问题。
著名的传播理论家 Harold Lasswell 在他 1948 年的文章《社会中的传播结构和功能》（_The Structure and Function of Communication in Society_）中写道：
> （一个）描述沟通行为的方便方法是回答以下问题：
>
> * 谁
> * 说什么
> * 在哪个渠道
> * 对谁
> * 有什么效果？
>
作为一名技术沟通者，你可以运用 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)
校对：[校对者ID](https://github.com/校对者ID)
本文由 [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/