读《开发团队中的文档编写者》

 

一般情况下，每一个开发小组都拥有一个或者更多的专业技术文档编写者，这些编写者负责为他们的产品编写出相关的技术文档。然而，并不是所有的公司能拥有专职的技术文档编写者。如果你必须编写出和你的软件产品联系在一起的技术文档的时候，你应该在你的脑子里记住下面的这些必须进行的事情。 需要进行分析 绝大多数技术文档编写者所做的第一件事情就是进行分析，而分析工作又可以分为两种：对象分析以及任务分析。 对象分析 在进行对象分析的时候，你应该明确这份技术文档是针对哪些人的，也就是什么样的人会阅读你的这份技术文档。此外，你是否正在为公司里别的开发小组编写应用编程接口(API)文件么?别的公司的开发人员是怎么样做的?你应该去了解阅读你所编写技术文档的那些人对于产品开发的内部过程了解多少，并且要知道公司内有哪些数据你可以使用，有哪些你不能使用? 有可能你正在为最终使用产品的用户编写技术性文档。你要弄清楚这些用户是使用计算机的菜鸟还是高手。这些用户是否包括各种不同的类型，或者他们的背景是否要不尽相同呢?如果你对这些情况并不确定的话，这里有一些办法能够帮助你确定这些情况。和你公司里的服务组或者技术支持小组的成员就这些问题进行交谈，这能够帮助你通过他们的经验来了解那些用户的情况。阅读有关此产品或者类似产品的新闻组以及邮件列表也可以让你获得有用的信息。你甚至可以在你们的网络站点上进行问卷调查，或者直接把问卷分发到那些注册过的用户手里来了解情况。不过，在这么做的同时要让这些人明白你是在为他们服务，这样才会获得更多的反馈。 任务分析 任务分析包括对读者将会如何使用这些技术文档进行分析。这份技术文档是为了指导用户如何安装软件产品而编写的么?如果是这样，你就要把精力集中在安装过程中每一步骤的上面。是否是为了方便其他编程者而编写的应用编程接口(API)文件?在这种情况下，你可能会需要一种基准格式来把应用编程接口(API)组件分解成逻辑排列的一些形式，这就让需要阅读这份文件的程序开发设计人员能够轻松的从中获得他们所需要的东西。 有些时候，把任务和相关参考文献结合在一起是一种更好的办法。在指导说明中可以包含参考文献部分，并且这是作为独立的内容而附加在指导说明上边的。另一些好办法是在这种指导说明中加入技巧、警告、注释、表、数据以及其它的一些内容，这样你就可以更生动的描述相关的内容，单纯的动用大量的文字很容易让读者产生沉闷的感觉。 在技术文档中加入图形注释 在技术文档中加入技巧和警告内容是非常重要的，这样能够避免让你的读者产生和别的指导说明书或者参考材料混淆的感觉。看一看别人编写的手册或者技术说明书，你就能够获得大量的范例。典型的情况是，在你所添加的技巧和警告周围加上边框，或者用醒目的下划线标注出来，对你的读者来说都是很有帮助的。在文章中加入图形也是一种好办法，尤其是你在向读者对某些事情进行警告的时候，图形化的内容能够让你所警告的东西变得更清晰让能够产生深刻的印象。 注意技术文档的措辞 对于技术性文档来说，另一个重要的方面就是你的措辞。如果你的文档所针对的对象是入门者或者没有技术背景的人，你必须对你的这些读者所拥有的知识进行分析，这是十分基本而且重要的。因为你不知道这些读者对你所引用的缩写词汇是否真的明白。为了避免你的读者对这些词汇感到头疼，一定要使用完整拼写的词汇，或者附加上一份缩写词汇表。有没有更简单的办法呢?公司里负责市场的副总裁很可能并不清楚什么是API，但是如果你把API写成“一套能够帮助软件设计人员让他们开发的软件能够同我们所开发的软件进行对话的工具”，这么写看上去很费笔墨，但是，这样却能够让那些没有技术背景的读者很好的掌握API的含义。 对于那些专业的技术人员来说，你就可以使用那些专业术语了(也就是说，你可以使用堆栈、线程等等词汇了)，并且写出这些词汇的同时，并不需要你再特别的解释一番。不过，如果你比不确定你所使用的一个缩写词是被广泛认可的，那么，一定要在后边把这个缩写词解释清楚，并跟上完成的拼写。不要过分使用那些冗长的词汇以显示你的词汇量。尽量使用简单的能够说明问题的措辞;这么做更能够给读者留些深刻的印象，而不是让你的读者把时间浪费在查字典上。对于专业技术人员以及非专业技术人员来说，你都应该这么去编写文件，这样才能收到良好的效果。 保持文档的前后一致性 最后，让我们来看一看保持文档内容一致性的重要性。你在文章的开始部分就应该决定使用米制长度单位还是使用英制长度单位。一些细微的地方你都应该做到前后统一，比如说，在文章前边使用了5MB，那么在文章后面就不应该出现5 MB;你也得决定是使用5英尺还是使用5'，等等这些问题你必须都要注意。当你使用到变量的时候，会出现这种有趣的情况：在使用变量内容的时候，你是会使用“variable = definition of value”的形式，还是会使用“variable = example value”的形式? 另外一个需要注意的事情是你对字体的使用，因为用户也许会需要做一些输入的工作。一些人会使用等宽字体，例如Courier，来让用户输入资料。还有要统一的是使用“下划线”还是使用“粗体字”。具体使用哪一种形式这可以由你所在职业领域所习惯所决定，但是通常来说，只要在你的文章中保持前后用法的一致性就可以了。在你进行文件编写的时候，边上应该放上一张伸手可及的白纸，以便于你纪录这些前后应该保持一致的用法以便于随后查询。 结论 能够有一位专职的技术文档编写作者来创作你所需要的技术性文档是非常好的事情，然而，有的时候出于某些原因，只有让软件开发设计人员自己动手来编写这些技术文档。虽然不是专业的技术文档编写者，但仍旧应该注意上面提到的那些问题，并且切实的把这些细节和注意事项都应用到技术文档的编写中去，这样才能够为你和你的用户们编写出随时可用并且易于阅读的技术文档。