HackMD
如何寫好技術寫作
tags: translation
節譯自
- https://mkaz.blog/misc/notes-on-technical-writing/
- HN 討論: https://news.ycombinator.com/item?id=21955306
原則
- 技術寫作的原則是為了幫助使用者快速且有效的完成任務
- 帶著使用者如何做而不只是呈現結果
- 儘快讓使用者達成「第一個成功」(First Success)
- 有不止一種的文件類型
- 用簡單且直白的方式來敘述
訣竅
- 了解你的目標客群和目的
- 最重要的事情要先講
- 使用子彈清單
- 一個段落一個概念
- 反覆修改打磨
避免後設書寫 (Avoid Meta Writing)
(這段就直接看例子吧)
You don’t need to tell the reader what you’re going to tell them. Just tell them.
- Bad: This chapter discusses the factors that cause names to rise and fall in popularity.
- Good: What makes a name rise and fall in popularity?
Don’t refer to sections or paragraphs in the writing.
- Bad: Summarizing the preceding section about…
- Good: In summary, …
Don’t tell the reader something is extremely complex; likewise don’t tell the reader something is simple. The reader will make up their own mind about a concept being easy or hard.
最簡化的步驟
- 以告訴使用者行動為準則。使用者通常想要做事。
- Anchor the tool in the task domain. A tool is a means to an end. This principle asks designers to select training tasks that are meaningful for the user.
- 提供遇到錯誤時的辨識和修復
- 提供延伸閱讀或研究資料
Read deeper about Minimalist Instruction from the Department of Instructional Technology at University of Twente, Netherlands.
建構主義 (Constructivism)
- 試著鼓勵讀者自己找出原則
- 把資訊解釋到合乎讀者目前的程度
- 以螺旋 (spiral) 的方式組織內容。讀者基於已經學會的知識，繼續學習新的
- 用主動會話的方式來吸引讀者，例如「請試試」，「看看結果」，「自己探索吧！」
不同的文件類型
- Tutorials – A tutorial is learning-oriented for newcomers, a directed set of lessons to give the user basic confidence and skills. A tutorial should not assume knowledge or language, but is there to take a beginner who doesn’t know what questions to ask through learning.
- How-to Guides – A how-to guide, or FAQ is goal-oriented, directed by the user. A how-to guide can assume the user has basic knowledge and language, but needs to know how to solve a specific problem.
- Explanation – An explanation or overview document is understanding-oriented providing background or additional detailed context.
- Reference Guides – A reference guide is information-oriented, it is accurate and complete describing the machinery. API documentation is an example of a reference guide.
