I tend to prefer documentation in the source. I think that this increases the chances of it being found and being maintained. In my Java world you can produce quite nice JavaDoc that can be extracted from teh source, including package-level overview material.
I would add explanatory overview material there, or in the primary entry point to the applciation, where my "main" is if I have one.
A README.txt actually in my source directory will also make it into my SCM so that can work too, but I just prefer some form of unity with the rest of my program documentation.
然后我添加快速入门指南和/或示例概述 - pdf 将是一种很好的格式，因为它允许您使用良好的格式并且易于阅读和打印。你说的概述是有用的，这是正确的。从最终用户的角度思考：“我从未见过这个 SDK，但我想做 XYZ。我应该先看哪里，我需要理解哪些关键概念？”。
主要要记住的是，尝试使用您的 SDK 的人以前从未使用过它，因此解释不应假定任何先验知识，而应涵盖基础知识。这就是大多数 SDK 文档失败的地方：作者是使用 SDK 的专家，他们的跳跃水平已经远远超出了读者的理解。或者他们记录了所有内容，因此最终用户被有关一千个 API 调用的信息淹没，但不知道首先调用哪个 API 才能开始。通常，一句话可以节省人们花费数小时/数天的时间通过示例/文档来试图弄清楚事情是如何工作的。
If possible, think of the most common scenarios and provide simple (ideally separate) samples for each of them. I find it is often very frustrating using a new SDK because the samples do one or two very specific things that are unrelated to my needs, so I am left in the dark about how to get started.
As to documentation, I'd start by ensuring the sample code is in a good clean coding style, and well commented (both in-code comments and DocXml/Doxygen function comments that can be read while coding and/or extracted to an externally readable format). This in itself should be enough to allow a good programmer to understand the samples (i.e. class comments should describe how/where/why the class is used, not just contain the name of the class with spaces between the words!)
Then I'd add a quick-start guide and/or overview of the sample - pdf would be a good format because it allows you to use nice formatting and is easily read and printed. You are right about overviews being useful. Think of it from your end user's point of view: "I've never seen this SDK and I want to do XYZ. Where should I look first, and what key concepts do I need to understand?".
The main thing to bear in mind is that the guy trying to use your SDK has never used it before, so the explanations should not assume any prior knowledge, and should cover the basics. This is where most SDK documentation falls down: The author is an expert in using the SDK and they leap in at a level that is already way above the understanding of their readers. Or they document everything so the end-user is swamped with information about a thousand API calls, but has no idea which one to call first to just get started. Often a single sentence can save somebody spending hours/days working their way through samples/documentation trying to figure out how things work.
发布评论
评论（2）
我倾向于更喜欢源代码中的文档。我认为这增加了它被发现和维护的机会。在我的 Java 世界中，您可以生成非常好的 JavaDoc，可以从源代码中提取这些文档，包括包级别的概述材料。
我会在那里添加解释性概述材料，或者在应用程序的主要入口点中添加解释性概述材料，如果我有的话，我的“主要”就是其中。
实际上在我的源目录中的 README.txt 也会将其放入我的 SCM 中，这样也可以工作，但我只是更喜欢与程序文档的其余部分进行某种形式的统一。
I tend to prefer documentation in the source. I think that this increases the chances of it being found and being maintained. In my Java world you can produce quite nice JavaDoc that can be extracted from teh source, including package-level overview material.
I would add explanatory overview material there, or in the primary entry point to the applciation, where my "main" is if I have one.
A README.txt actually in my source directory will also make it into my SCM so that can work too, but I just prefer some form of unity with the rest of my program documentation.
如果可能，请考虑最常见的场景，并为每个场景提供简单（最好是单独的）示例。我发现使用新的 SDK 通常非常令人沮丧，因为示例会执行一两个与我的需求无关的非常具体的事情，因此我对如何开始一无所知。
至于文档，我首先要确保示例代码采用良好干净的编码风格，并且注释良好（代码内注释和 DocXml/Doxygen 函数注释都可以在编码时读取和/或提取到外部可读的文件）格式）。这本身应该足以让一个好的程序员理解示例（即类注释应该描述如何/在哪里/为什么使用该类，而不仅仅是包含类的名称，并且单词之间有空格！）
然后我添加快速入门指南和/或示例概述 - pdf 将是一种很好的格式，因为它允许您使用良好的格式并且易于阅读和打印。你说的概述是有用的，这是正确的。从最终用户的角度思考：“我从未见过这个 SDK，但我想做 XYZ。我应该先看哪里，我需要理解哪些关键概念？”。
主要要记住的是，尝试使用您的 SDK 的人以前从未使用过它，因此解释不应假定任何先验知识，而应涵盖基础知识。这就是大多数 SDK 文档失败的地方：作者是使用 SDK 的专家，他们的跳跃水平已经远远超出了读者的理解。或者他们记录了所有内容，因此最终用户被有关一千个 API 调用的信息淹没，但不知道首先调用哪个 API 才能开始。通常，一句话可以节省人们花费数小时/数天的时间通过示例/文档来试图弄清楚事情是如何工作的。
If possible, think of the most common scenarios and provide simple (ideally separate) samples for each of them. I find it is often very frustrating using a new SDK because the samples do one or two very specific things that are unrelated to my needs, so I am left in the dark about how to get started.
As to documentation, I'd start by ensuring the sample code is in a good clean coding style, and well commented (both in-code comments and DocXml/Doxygen function comments that can be read while coding and/or extracted to an externally readable format). This in itself should be enough to allow a good programmer to understand the samples (i.e. class comments should describe how/where/why the class is used, not just contain the name of the class with spaces between the words!)
Then I'd add a quick-start guide and/or overview of the sample - pdf would be a good format because it allows you to use nice formatting and is easily read and printed. You are right about overviews being useful. Think of it from your end user's point of view: "I've never seen this SDK and I want to do XYZ. Where should I look first, and what key concepts do I need to understand?".
The main thing to bear in mind is that the guy trying to use your SDK has never used it before, so the explanations should not assume any prior knowledge, and should cover the basics. This is where most SDK documentation falls down: The author is an expert in using the SDK and they leap in at a level that is already way above the understanding of their readers. Or they document everything so the end-user is swamped with information about a thousand API calls, but has no idea which one to call first to just get started. Often a single sentence can save somebody spending hours/days working their way through samples/documentation trying to figure out how things work.