记录编程语言：参考手册

我们正在寻找整个产品线的文档更新。的那部分包括参考手册用于编程语言用作系统的一部分。

在编写用于编程语言的参考手册时，为使该语言的新手拥有最大的可用性，最好的构造方法是什么？

记录每个关键字的关键方面是什么？

• 句法
• 描述
• 参数-如果适用
• 返回值-如果适用
• 用法示例？
• 还有其他我想念的吗？

概念（例如锁定策略，与性能相关的详细信息）是否也应在本参考手册中进行记录，或者是单独的文档？

_{这是供外部消费。我们已经有完整的文档集（请参阅：http : //www.rocketsoftware.com/u2/resources/technical-resources）。制定出我们应该做的事情与众不同-我已经有了我的想法，但是和往常一样，我尽量不要仅仅依靠我的观点。}

_{受众：技术开发人员使用我们的数据库和工具来跨许多行业生产软件。}

根据目标受众的需求组织文档。

在您的情况下，主要受众显然是软件开发人员。这里要考虑的部分是解决这一方面的不同“子受众”：

1. 你好，世界。
   那些愿意快速领会它的味道的人，只需构建并运行示例应用程序即可查看它的外观。
   将观众想像成MySQL提出的“ 15分钟规则”：
   

   _{...用户可以在完成下载15分钟后启动并运行MySQL。}

2. 基本原理。
   对于愿意快速学习开始生产可用软件的人来说。
3. 高级主题。
   对于已经非常熟悉并熟悉基础知识的开发人员，有兴趣知道其以外的内容。基础知识尚未涵盖的主流主题。
4. 样式指南/推荐做法。
   对您对如何推荐做事方式感兴趣的人的主观建议和指导。
   _{该问题并没有说明您的案例是否会吸引大量读者，因此要考虑的选项是将其作为“ 高级”主题的一部分/附录甚至完全删除。}
5. 怪癖。
   除了主流之外，晦涩难懂的话题可能会引起相当一部分观众的兴趣。例如，如果您有旧产品线，或诸如升级/迁移/与旧产品的互操作性之类的信息，请放在此处。如果在特定的“外来”环境中某些功能存在某些副作用，则此部分进行说明。

^{如果手册中的问题可疑/模棱两可怎么办？如果事实证明对特定概念的透彻解释会使该手册难以阅读？如果发现手册的特定版本有错误怎么办？}

维护者需要考虑的两件事是：

1. 技术/正式规格。
   每当本手册中有一个可疑/模棱两可/难以解释的主题时，都可以参考规范中的特定段落，以对读者进行严格而清晰的“正式”声明。对语言语法进行严格而完整的描述（并且很可能很无聊）会更好。规范最重要的
   考虑因素是技术准确性和完整性，即使这些代价是以可读性为代价的。
2. 在线补充。
   只需保留一些URL并将其放在您发布的每个文档的开头，以便使人想知道他们刚刚读的书到底能去哪里（而不是烦扰手动维护人员）并找到所解释的错误。

   _{勘误>基础知识>版本2.2>错字，第28页，第二句话以运气开头，改为锁定。}

例如，手动维护人员显然会对并发性的完整，准确描述和正式规范中的锁定感兴趣-将其放在此处。基础知识或高级主题的读者可能会对从规范中提取并针对其需求量身定制的概述/简介/指南感兴趣。

_{安排对其他语言（例如您的语言）提供的参考文档进行比较研究可能会有所帮助。本研究旨在利用以前的研究人员的经验，并学习如何避免他们犯的错误。}

_{最后但并非最不重要的一点是，考虑以与软件开发类似的方式设置文档开发。我的意思是诸如版本控制，常规发行，问题跟踪，质量保证等。您可能要做出一些让步，尽管事实证明您的技术撰稿人对这种事情不太满意。我们不想以糟糕的内容“换取”完美的开发过程，是吗？}

您需要做的第一件事是评估受众。您的读者是Linux内核黑客，还是使用软件工具来完成工作但对软件本身不感兴趣且没有CS背景的硬件设计师？电气工程师可能不太清楚const和非const参数之间的区别，对象与引用的指针之间的区别等。如果您的原语名称重载，那么您最好在适当的层次上为您的读者解释该概念，如果他们是C ++程序员，那可能什么都不是。

您需要评估的第二件事是语言原语的粒度。粒度越细，您将需要提供更多的示例来接近每个基元的语法规范。也就是说，如果您有一个可实例化某些上下文的低级原语，并且需要先使用其他三个低级原语对其进行操作，然后才能执行任何有用的操作，那么最好提供一个完整的示例来说明一些有用的函数close-通过在手册中。有关几乎无法使用的文档的出色反例，请参见在线openssl文档。

确保包括对功能任何副作用的说明。

无论如何，如果您不希望客户的程序员每天晚上睡前诅咒您，请提供大量经过测试的示例代码，它们执行一些高级功能基元。确保这些示例不仅是代码片段，而且是开箱即用的完整，可编译或可运行的示例。

传统上，技术作家区分参考手册和用户指南。参考手册通常包括语法规范，功能或原语的可理解定义，有关陷阱，性能和副作用的讨论以及简短的示例用法。用户指南包括更多扩展的用法示例以及对更广泛的工程问题的讨论。Kernigan和Ritchie的“ C编程语言”是该约定的一个很好的反例，但是这种方法仅在您所记录的语言相对简单时才有效。

作者于1987年至1991年期间担任Ready Systems Inc开发中心工程服务部经理，负责管理由五个技术作家组成的团队。