Pecan: 文档大纲

@robkooper和@ashiklom试图将您的两个大纲想法结合起来。 @KristinaRiemer和@bailsofhay很高兴收到您的反馈。 很快就会开始实施，这样我们就可以在月底之前将页面移动到我们想要的地方。

我觉得这看起来真的很好。 这只是重新排列现有材料，而不是添加任何东西？

当你这样做时，第 41 章实际上应该在 40 章之前。

@KristinaRiemer是的，我只是要移动一些东西。 与此同时，我们可以找出缺失的东西并提出问题。 请注意，这被标记为“史诗”问题，因此可以在此问题下链接这些其他问题，以便我们保持井井有条。

我只是在查看文档中的一些行话，以便快速写下我的工作。 我意识到该文档没有对为什么有人想要使用山核桃的最佳解释（特别是它缺少对不确定性分析的任何解释）。 将其放在当前可用文档的“项目概述”部分是有意义的，但不确定将其添加到我们正在处理的重组文档的何处。

来自@infotroph关于文档的链接： https : //www.divio.com/blog/documentation/

来自@infotroph关于文档的链接： https : //www.divio.com/blog/documentation/

更多上下文：这篇文章提出了一个强有力的案例，即有四种不同类型的软件文档，并且所有记录良好的项目都需要将所有四种作为明确分开的部分：

• 教程，用于使用分步示例向初学者教授您的工具的功能，这些示例保证每次都完全按照描述的方式工作
• how-tos ，用户可以在其中回答“我如何......？”形式的问题的食谱部分，仅包含他们需要的给定问题的详细信息
• 参考，有关如何调用事物、它们使用什么协议以及它们返回什么值的手册页详细信息
• 讨论，您可以在其中解释为什么事情会按照它们的方式工作，提供背景信息，就好的与坏的做法提出建议，并以其他方式提供不适合其他部分的上下文。

这个问题是陈旧的，因为它已经开放了 365 天，没有任何活动。

从长远来看，我认为教程/操作方法/参考概念是可靠的，我们仍然可以通过更统一地应用它来澄清文档。 但是这里最初讨论的重组已经完全实现，我将关闭这个问题并鼓励新线程进行任何进一步的清理。