[Framers] OT-Documenting APIs

[Robert Lauriston]

The kinds of API docs I would distinguish are:

1. generated from source code using native tools (e.g. javadoc and pydoc)
2. generated from source code using native code comments and a
third-party tool (e.g. Python docstrigs + Sphinx)
3. generated from source code using third-party tools (e.g. C++ &
Doxygen, REST & Swagger / OpenAPI)
4. generated from doc source in the same codeline as the source code
(e.g. Markdown + static site generator)
5. not generated from source code, tech writer just works with the
developers to sort it out

There's overlap among those categories, especially 3 to 5, but I think
from a tech writer's point of view those are the major variations in
workflow. 1-3 guarantee accuracy in certain aspects of the docs:
deprecated code will automatically be removed, and new code that has
not been documented yet will typically result in obvious holes so
you'll know you need to fill them in.

I think #4 became popular because developers chose REST over javadoc
to avoid the time and effort required to support generating the docs
from the source. In the long run, that's not cost-effective and leads
to inferior docs, which is why Swagger has caught on.

On Thu, Nov 23, 2017 at 2:59 AM, Shmuel Wolfson <shmuelw1 at gmail.com> wrote:
>... I think there are two different types of APIs:
> 1. A list if software functions
> 2. Web-based commands that allow you to interact with website applications
>
> The two types seem very different. I write software reference manuals that
> are like #1 above, but the API documentation examples here don't look
> anything like what I write:
> https://github.com/PharkMillups/beautiful-docs ...