创建技术文档时应避免的7件事

技术写作不同于其他形式的写作。 其目的通常是提供有关该主题的指导,以帮助用户解决问题。 由于技术写作具有如此独特且明确的目标,因此好的技术写作必须遵循特定的准则。 让我们看一下编写技术文档时应避免的一些最重要的事情。 1)语言模糊 “短时间”是多长时间?“大量”是多少?“空”,“显着”,“以后”,“沉重”和“许多”等模糊的描述符是开放的要解释,因此模棱两可。 此外,这些术语在时间上是相对的:35年前被认为是“短时间”的东西很可能会在将来被判定为“长时间”。 技术的进步会使使用这种语言的技术文档过时,因此请始终尝试尽可能具体。 2)被动语态 主动语音比被动语音更强更直接。 例如,最好说“ 使用您的帐户信息登录”,而不是“使用您的帐户信息登录”。活动的声音通常更清晰,更简洁。 就是说,有时候技术写作者会使用被动语态:例如,当主题未知或不如宾语重要时,或者主动语态暗示读者应为可能超出其阅读范围的情况负责控制。 考虑“如果无法启动系统…”和“如果无法启动系统…”之间的区别。 3)不必要的信息 使您的文章简短明了。 如果它不能帮助用户解决问题,则需要解决。 请勿包含有关技术或营销语言的内部运作的琐碎细节,这些技术或营销语言称赞它是工程学的胜利。…

如何保持写作动力

在西雅图和波特兰之间写美铁 在西雅图到布雷默顿(Natural-to-Bremerton)轮渡的自助餐厅里,戴着耳机,手提电脑发光,令我感到惊讶的是,在下雨的星期四下午,像我一样,还有多少人在2点喝啤酒。 在不来梅顿,我找到了一家咖啡店,写信直到轮渡回东部,在那儿,到处都是喝啤酒的海军男人和女人包围着那晚的棒球比赛。 它不是很漂亮,但是可以完成工作。 到西雅图时,我在下一本书中又增加了1200个字。 最近,我发现我写的每个单词都是经过艰苦奋斗和一系列妥协的结果。 我下班休息一个下午写吗? 离开我的妻子和孩子找几个小时? 跳过午餐挤出几句话? 是的,我愿意。 一些作家发现NaNoWriMo长达一个月的承诺是他们的动力,我对此表示赞赏。 但是,如果您达不到50,000字的目标怎么办? 或者,如果您只击中50k才意识到自己已经到了一半,该怎么办? 您如何保持发展势头? 多年来,寻找动力,寻找正确的时间和地点的动力一直困扰着我。 像许多作家一样,我梦想着神话般的海明威套路:在黎明时醒来,在中午敲出一千个单词,在下午充饥或娱乐,直到可以喝鸡尾酒为止。 近十年来,在三本书的过程中,我设法偶尔维持了那个周期的适度版本,有时达到了海明威描述的黎明前的流动状态:“没有人打扰您,无论是冷还是冷,您来对您的工作充满热情,在您写作时也是如此。” 然后,写作生活的现实在我身上崩溃了,又是时候做一份日常工作了。…