翻译自Notes on Technical Writing，作者
Marcus Kazmierczak。
在过去的一年中，我处理过WordPress的文档。在冻结发布期间，我开始做出贡献，以帮助开发人员过渡到新平台。我发现编写文档是我的最爱，并且乐于帮助和教育人们。尽管这不是我工作的主要部分，但我仍然在这里和那里找时间继续努力。
这一次，我阅读了有关技术写作和文档的各种资源。这些是我的笔记，既可以帮助我以后记住，又可以作为帮助我考虑现在写的工具。
Principles
在编写文档时，我尝试牢记以下原则：
- 技术写作的目的是帮助用户尽可能快和高效地完成任务。#
- People learn by doing, prefer to be shown and not told
- Get users to their first success quickly
- 有不止一种类型的文档
- 保持简单，用平易的语言
Tips
- Know your audience, know your purpose
- Put the most important information first
- Use bullet lists（使用无序符号列表）
- One idea per paragraph
- Edit, Edit, Edit（不断改进）
Avoid Meta Writing
避免写关于文字的文章，文字没有自己的想法。 活跃的部分是作家和读者。
您无需告诉读者您将要告诉他们的内容。 告诉他们：
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?
不要在写作中引用章节：
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.
Minimalist Instruction
John M. Carroll和他在IBM的同事研究了创建支持文档的过程，分析了使用户精通的最佳方法。在1980年代，他们开发了一种极简主义的方法，并创建了精彩的IBM Displaywriter操作员培训手册，想象一下必须首先向某人介绍使用文字处理器的情况。
极简主义教学的四个原则：
- 选择一种面向行动的方法。 用户通常想做事。 该原则反映了极简主义的以用户为中心的本质。
- 将工具锚定在任务域中。 工具是达到目的的手段。 该原则要求设计人员选择对用户有意义的培训任务。
- 支持错误识别和恢复。 人非圣贤孰能无过。 有几种方法可以提高用户处理错误的能力和舒适度。
- 支持阅读做，研究和定位。 设计必须尽可能满足目标受众的不同需求和倾向。 该原则反映了极简主义的以用户为中心的本质。
从荷兰特温特大学的教学技术系中进一步了解极简主义教学。
Constructivism
美国心理学家杰罗姆·布鲁纳（Jerome Bruner）研究了人类的认知心理学。布鲁纳著作的一个主要主题是学习是一个活跃的过程，学习者可以根据自己的知识构造新的想法。将建构主义原理应用于文档：
- 尝试鼓励读者自己发现原理。
- 将信息转换为适合读者当前水平的格式。
- 螺旋式组织材料，因此它会继续建立在他们已学到的知识之上。
- 参与活动对话框，邀请用户执行“请尝试”，“看看会发生什么”，“探索自己”。
进一步了解布鲁纳和构建注意理论
Types of Documentation
丹尼尔·普罗奇达（Daniele Procida）撰写了What nobody tells you about documentation，（至少）有四种文档：
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.
Resources
- On Writing Well (book) The classic guide to writing non-fiction by William Zinsser.
- Basic Writing Tips an article by Andrew Etter
- Wordiness: Danger Signals (2 page pdf) by Margaret Procter, University of Toronto
- Writing is Thinking by Sally Kerrigan, A List Apart
- Writing is Thinking, by Steph Smith
- Tips on Writing a Great Science Paper from Cormac McCarthy
- Microsoft Writing Style Guide