<story><title>Four kinds of documentation</title><url>https://www.divio.com/blog/documentation/</url></story><parent_chain><item><author>protomikron</author><text>My pet peeve is auto-generated documentation from configuration files or source code. It is absolutely useless and I would rather prefer no documentation than auto-generated.&lt;p&gt;Some time ago Swagger (nowadays OpenAPI) got really popular and many projects &amp;quot;had an API&amp;quot; and pointed users to their green autogenerated API documentation clusterfuck. When time went on this green page would become an indicator for me, that the project does not work and I should be very sceptical - I am sure there are projects that do it better, but for me &lt;i&gt;no-content&lt;/i&gt; auto-generated documentation is a real code smell.</text></item></parent_chain><comment><author>dtech</author><text>I do not share your experience, because in my experience the auto-generated docs will be kept in sync with the code&amp;#x2F;API while a separate specification will become outdated over time.&lt;p&gt;This does of course require human-readable description in all the endpoints. But that&amp;#x27;s the same as only an autogenerated function signature in code documentation vs an added human-readable description.</text></comment>
<story><title>Four kinds of documentation</title><url>https://www.divio.com/blog/documentation/</url></story><parent_chain><item><author>protomikron</author><text>My pet peeve is auto-generated documentation from configuration files or source code. It is absolutely useless and I would rather prefer no documentation than auto-generated.&lt;p&gt;Some time ago Swagger (nowadays OpenAPI) got really popular and many projects &amp;quot;had an API&amp;quot; and pointed users to their green autogenerated API documentation clusterfuck. When time went on this green page would become an indicator for me, that the project does not work and I should be very sceptical - I am sure there are projects that do it better, but for me &lt;i&gt;no-content&lt;/i&gt; auto-generated documentation is a real code smell.</text></item></parent_chain><comment><author>xtiansimon</author><text>I&amp;#x27;ve been trying to get my head around a particular Swagger project. Here is a funny email exchange from my request for documentation:&lt;p&gt;...
Hi, I reaching out to to ask if I could get my hands on some documentation because the API is somewhat a black box to me.&lt;p&gt;...
The api documentation for [product] can be found here: &lt;a href=&quot;https:&amp;#x2F;&amp;#x2F;api.[product].com&amp;#x2F;&quot; rel=&quot;nofollow&quot;&gt;https:&amp;#x2F;&amp;#x2F;api.[product].com&amp;#x2F;&lt;/a&gt;&lt;p&gt;...
Sorry. That&amp;#x27;s not what I mean by &amp;quot;documentation&amp;quot;. It&amp;#x27;s certainly non-linear. I don&amp;#x27;t know how to &amp;quot;read&amp;quot; this site to gain an understanding. It&amp;#x27;s kinda sparse:&lt;p&gt;&lt;pre&gt;&lt;code&gt;   GET &amp;#x2F;v2&amp;#x2F;adjustments &amp;gt; Implementation Notes: Fetches a list of adjustments.

   GET &amp;#x2F;v2&amp;#x2F;reportCategories &amp;gt; Implementation Notes: Fetches a list of report categories.
&lt;/code&gt;&lt;/pre&gt;
...
Hm, I think swagger documentation is pretty standard among APIs I&amp;#x27;ve worked with before. I&amp;#x27;m pretty sure it&amp;#x27;s all they have.&lt;p&gt;...
&amp;quot;Swagger Documentation&amp;quot; is a special class of documentation for sure; Nobody likes writing documentation.&lt;p&gt;Talk about insider (them)&amp;#x2F;outsider (me).</text></comment>