Here is a template I use to document web applications, web services and microservices.
It has to give all the information so a person who is new to that application can understand it and can start working on it. However it should not be too long otherwise people won’t read it or maintain it. You have to keep it simple.
It will not contain too much of technical information, the developer will find it in the source code of the application (ex: in a README.md)
- Overview: a one liner that describes what this application does and who uses it
- Features: the complete list of features (each feature = one line, can be written as user stories)
- Source Code: Where to checkout the source code
- Environments: URLs and ports that are opened. Describe the use of each port and the protocol that has to be used (ex: HTTPS 1800 main application entrypoint, HTTP 6900 monitoring, etc.)
- Functional Details: what are the main entities this application uses? what are the possible values for some specific fields? Also explain and define the main topics that will be discussed when working on this application (acronyms, business terms, etc.), it can be written like a glossary. UML can also be used (if it is simpler than words, like a sequence diagram that explains a complex feature). External documentation can be referenced here.
- How to deploy the application: in test and prod environments. Specify about CI/CD environments. If prod deployments are not automated, describe carefully the procedure to follow.
- Monitoring: what are the endpoints used to monitor the application? How could I know that an application runs properly?
- Dependencies "uses": what uses this application? Any database, application, files that is used by this application should be listed.
- Dependencies "used by": who uses this application? Any kind of user or application that uses this application should be listed.
- Entrypoints: list of entrypoints of the application: URL + port + short description (can be replaced by doc-in-code URL, like Swagger)
- Samples: for web services, a table with each HTTP request and possible HTTP responses (including HTTP 4xx and HTTP 5xx errors). It can also be replaced by a Swagger-like documentation.
- How to run tests: script to run to ensure that the application is working properly. Also include performance tests scripts location and how to run them.