Documentation

Here I would like to keep references to good documentation examples, mostly aimed for software developers.

WEB API design and documentation

Documenting web api using Swagger + Swashbuckle:

• ASP.NET Web API documentation using Swagger – Introduction
• ASP.NET WEB API documentation using Swagger – Global operation for 500 response code
• ASP.NET Web API documentation using Swagger – Use schema mapper for generic data types
• ASP.NET WEB API documentation using Swagger – Update schema using SchemaFilters and FluenValidator rules
• ASP.NET Web API documentation using Swagger – Add custom headers

Designing REST API references:

• Microsoft REST API Guidelines

Tools to create diagrams

Sequence diagrams for basic scenarios:

• https://www.websequencediagrams.com
  Allows to create digrams using DSL, so it is also possible to use version control system to store them

Flow charts:

• https://draw.io
• https://www.lucidchart.com

General purpose tool:

• Visio

Other references

Domain agnostic:

• 14 Examples of Documentation Mistakes You Are Making
• Does Your Documentation Connect the Dots?