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 <[email protected]> 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 ... _______________________________________________ This message is from the Framers mailing list Send messages to [email protected] Visit the list's homepage at http://www.frameusers.com Archives located at http://www.mail-archive.com/framers%40lists.frameusers.com/ Subscribe and unsubscribe at http://lists.frameusers.com/listinfo.cgi/framers-frameusers.com Send administrative questions to [email protected]
