如果你喜欢写作和技术,技术写作可能是一个适合你的职业。如果你喜欢技术,但又不是真的整天喜欢编码,也可以做一些别的事情。
如果你喜欢通过教导他人来学习,为开源项目做出贡献,并教导他人如何做到这一点,或者基本上喜欢通过你的写作以简单的方式解释复杂的概念,技术写作也可能适合你。
让我们深入了解基础知识,了解你在开始技术写作时应该知道和考虑的问题。
技术写作是一门艺术,提供细节导向的指导,以帮助用户理解特定的技能或产品。
技术写作者的交流方式是将技术信息呈现给读者,使读者能够将这些信息用于预期的目的。
技术写作者也是是终身学习者。由于这份工作需要用简单而直接的术语来表达复杂的概念,所以你必须精通你所写的领域,或者愿意学习它。
这很好,因为每研究和编写一份新的技术文档,你就会成为该领域的专家。
除此以外,你还可以为开源社区做贡献,参与GoogleSeasonofDocs和Outreachy等付费开源项目。
你也可以把技术写作作为一个全职职业——很多公司都需要有这些技能的人。
知道如何实现功能并不一定意味着你可以与其他人清楚地交流该过程。
为了成为一名优秀的老师,你必须具有同理心,能够以适合你的目标受众的方式教授或描述术语。
我相信,作家是天生的,而不是后天的,而你只有通过实际写作才能学会如何写作。
你可能永远都不知道你有写作的能力,直到你把笔放到纸上。而要想知道自己是否有一定的写作能力,只有一个办法,那就是通过写作。
所以我鼓励你从今天开始写作。你可以选择从我在本节中列出的任何一个平台开始,以扩展你的写作能力。
当然,拥有一些技术领域的经验也是巨大的好处。
你还可以加入有用资源的链接,这样你的读者只需点击一下就能获得他们需要的信息。
为了知道你是为谁而写,你必须尽可能多地收集关于谁将使用该文件的信息。
重要的是要知道你的读者是否在该领域有专业知识,是否这个话题对他们来说是全新的,或者他们是否介于两者之间。
你的读者也会有他们自己的期望和需求。当读者开始阅读文档时,你必须确定他们在寻找什么,以及他们将从中获得什么。
要了解你的读者,请在开始写作之前先问自己以下几个问题:
这些问题还能帮助你思考读者在阅读你的写作时的体验,这一点我们现在要多说几句。
用户体验在技术文档中和在网络上的任何地方一样重要。
既然你知道了你的受众和他们的需求,就要记住文档本身是如何为他们的需求服务的。很容易忽略读者实际会如何使用文档。
写作时,不断后退一步,把自己当成读者来看待文档。问问自己:它是可访问的吗?你的读者将如何使用它?他们何时会使用它?是否易于阅读?
目的是编写一个对读者有用和可用的文档。
记住你的用户是谁,然后你就可以对你的文档进行构思和规划。
这个过程包括许多步骤,我们现在将继续进行。
在规划你的文档时,你必须研究你要写的主题。有大量的资源只需在谷歌上搜索一下就可以供你消费,并从中获得更深的见解。
尽可能多地使用谷歌,从研究期刊、书籍或新闻中获取事实和数据,尽可能多地收集有关你的主题的信息。然后你就可以开始做一个大纲了。
在扩展文档内容之前先列出提纲,这有助于你更专注地写作。它还可以让你组织你的思路,实现你的写作目标。
在确定需要嵌入到文档不同部分的各种虚拟辅助工具(信息图、gif、视频、tweet)时,有一个大纲非常有用。
终于,你可以开始写作了!如果你已经完成了所有这些步骤,写作应该会变得容易很多。但你仍然需要确保你的写作风格适合技术文档。
写作需要通俗易懂、直接和专业,在技术文档中不欢迎花哨或情绪化的文本。为了帮助你保持这种风格,这里有一些你应该培养的关键品质。
主动语态是指句子的主语是主动执行动词动作的人,被动语态是指主语是动词动作的接受者。
这是一个被动语态的示例:每个Web开发人员每年应阅读六次文档。
下面是一个主动语态的例子:每个web开发人员一年应该阅读该文档6次。
词语选择很重要,确保你使用最适合上下文的词汇。避免过度使用代词,如“它”和“这”,因为读者可能难以识别它们指的是哪个名词。
还要避免使用俚语和粗俗的语言——请记住,你是在为更多的读者写作,他们的性格和文化倾向可能与你不同。
如果你是你所在领域的专家,很容易使用你熟悉的行话,而没有意识到它可能会让其他读者感到困惑。
你还应该避免使用以前没有解释过的首字母缩写词,这是一个例子:
改进:渐进式网络应用(PWA)是真正的多平台开发的未来。它们在Android和iOS上的可用性使PWA成为未来的应用。
避免使用冗长的大词,总是尽量以最清晰的方式解释概念和术语。
一堆文字很难读懂,即使是最清晰的指令也可能在视觉表现不佳的文档中丢失。
他们说,一张图片胜过千言万语,即使在技术写作中也是如此。
但是,并非任何图像都可以配上,仅用文本表达技术信息是困难的,放置恰当的图像或图表可以澄清你的解释。
人们也喜欢视觉效果,所以把它们插入到正确的位置是有帮助的。看看下面的图片:
首先,这是一个没有视觉效果的博客片段:
这是同一博客的片段,但带有视觉效果:
贴心的格式、模板和图片或图表也会让你的文字对读者更有帮助。
既然你已经决定开始从事技术写作,这里有一些不错的平台,你可以在那里免费发布技术内容。他们还可以帮助你建立一个吸引未来雇主的投资组合。
你的申请可能被接受,也可能被拒绝,但不要灰心。你总是可以在以后重新申请,因为你变得更好,谁知道呢?你可能会被录取。
就像其他领域一样,技术写作也有各种流程、规则、最佳实践等。
参加技术写作的课程会帮助你完成你需要学习的每一件事,也可以给你很大的信心,开启你的写作之旅。
你可以查看以下一些技术写作课程:
成为一个社区或论坛的一部分,与那些和你有同样热情的人一起是有益的。你可以得到反馈、纠正、技巧,甚至从社区中的其他作家那里学习一些风格技巧。
以下是一些社区和论坛供你加入:
在我的技术写作之旅中,我跟随了一些伟大的技术作家,他们的写作之旅、一致性和风格都激励着我。
这些都是我仰望的作家,他们被我视为技术写作的虚拟导师。有时,他们会给我一些技术写作技巧,我觉得很有帮助,也从他们那里学到了很多东西。
以下是其中一些作家(与他们的Twitter超链接):
你不需要技术写作的学位就可以开始发布技术内容。你可以开始在你的个人博客和公共GitHub知识库上写作,同时构建你的作品集并获得实践经验。
真的——开始写吧。
通过为现有程序或项目创建新的文档来练习。GitHub上有很多开源项目,你可以查看并添加到他们的文档中。
技术作家一直在学习。通过深入到新的主题领域,并接受外部反馈,一个优秀的作家永远不会停止磨练自己的技艺。
当然,优秀的作家也是贪婪的读者。通过检查大量阅读和使用的文档,你的写作能力肯定会得到提高。