技术写作建议

本指南汇编了有关技术写作的建议和见解，尤其是对于网络技术和博客，是从经验丰富的专业人员和个人经验中汲取的。

选择您的话题：

理想的话题是您热衷和个人投入的话题。您的热情将散发出来。正如克里斯·科伊尔（Chris Coyier）明智地建议：“写一篇文章，希望在您搜索某些东西时找到您的文章。”虽然基于任务的写作可能是有效的，但个人联系会提高质量。

在知识新鲜时写作：

最好的写作时间是在学习新知识之后立即。体验仍然是生动的，使您可以传达“之前”和“之后”的理解。即使记下有关学习过程的快速记录，以后也可能很有价值。考虑到曼努埃尔·马图佐维奇（Manuel Matuzovic）举例说明的“今天我学到的”方法。

利用比较：

一种强大的，未充分利用的技术正在将新技术与熟悉的技术进行比较。雷切尔·安德鲁（Rachel Andrew）建议向熟悉JQuery的人解释现代JavaScript技术，并弥合了新的和已知的差距。这种方法将陌生的基础联系起来。

制作引人入胜的介绍：

一个共同的陷阱未能清楚地陈述文章的目的，并尽早瞄准受众。雷切尔·安德鲁（Rachel Andrew）强调了简洁介绍的重要性，该简洁介绍立即阐明了主题并打算读者。布莱恩·里纳尔迪（Brian Rinaldi）补充说，写得很好的介绍性段落可以确定读者是否继续。

清晰简洁的标题：

Erin Kissane倡导清晰的描述性标题，优先考虑清晰的清晰性。诸如“从GraphQl，Phoenix和React开始入门”之类的明确标题要优于模糊的Clickbaity。清晰度有益于读者理解和SEO。

Outro的艺术：

本·哈珀恩（Ben Halpern）强调了结论段落的重要性，这通常是引言后的第二读部分。虽然简单的摘要（“告诉'em你告诉你的'em”是有效的，但精心制作的结论加强了信息并提供了封闭。

增强扫描性：

Brian Rinaldi强调了分解大量文本以提高可读性的重要性。技术包括使用子标题，列表，相关图像和屏幕截图，说明性图形，简洁视频，良好的代码块，表格和可折叠<details>/<summary></summary></details>截面<details>/<summary></summary></details> 。诸如间距，颜色和对齐方式之类的设计元素的战略使用进一步提高了扫描性。

主动的语音和单词选择：

Katy Decorah和Neal Whitman强调使用活动语音（“服务器处理请求”）而不是被动语态（“请求是由服务器处理”）。避免诸如“ Just”之类的词，这可能是屈尊的，通常是不必要的。

保持语气和声音：

音调（您怎么说）应该与上下文保持一致。友好，权威，热情和感恩的语气通常适合技术写作。即使在调整不同情况下的语气时，声音（您的个性）也应保持一致。

管理长度：

技术写作通常遭受过多的长度。韦德·克里斯滕森（Wade Christensen）建议采用残酷的编辑方法。虽然太短的帖子也有问题，但清晰度和有用性应该是主要重点，而不是单词计数。只有在零件在主题上是独特且独立的，才能将长篇文章分为一个系列。

克服作家的障碍：

恐惧和自我怀疑是技术博客的常见障碍。马克斯·伯克（MaxBöck）建议一旦涵盖了基本要点，就会忽略“尚未准备就绪”的声音。杰里米·基思（Jeremy Keith）建议不要保留选秀，因为它们通常还没有完成。请记住，即使是小贡献也可能有帮助（Matthias Ott）。阿里·斯皮特尔（Ali Spittel）指出，即使是初学者也有宝贵的观点。

风格和创造力：

萨拉·索伊丹（Sara Soueidan）强调，没有一个完美的写作风格。做你自己，让你的个性在保持清晰度的同时发光。尝试创意格式，例如带注释的对话或视频系列。

以初学者为中心的内容：

尽管网络充满了初学者级内容，但写得很好的介绍性文章可以脱颖而出。清晰度对于所有技能水平都是有价值的。

现实世界的例子与抽象：

克里斯汀（Christine）强调了现实世界中的重要性来说明复杂的概念。但是，避免损害清晰度的例子。当有效使用时，抽象可以很大。

博客的好处：

博客可以增强职业前景，展示专业知识并提高理解。 Khoi Vinh将博客描述为“放大器”。

练习和改进：

一致的写作和出版对于改进至关重要。 “用赌注写作”（公开分享您的工作）是最有效的学习方法。

找到你的声音：

首先简单地分享您的知识。通过结合个人经验，引用他人并进行研究来增强您的写作。

来宾发布：

如果投放到网站，请仔细审查其准则。

有用的工具：

建议使用用于协作的Dropbox纸和用于校对的语法工具。

以上是技术写作建议的详细内容。更多信息请关注PHP中文网其他相关文章！