First of all, you need to understand you are not writing documentation for you, nor for your current team. You are writing documentation for the future developers that were not there when you first wrote this code. Worst of it, they might think it is bad code for many reasons and won’t understand why you wrote this way.
Taken from: How to write good software technical documentation
- Code documentation
- Function header comments
- Product documentation
- Software architecture schemas
- Database schemas
- Sequence diagram
- Technical decision log
You can put this information in the readme.md file
- how to install
- how to run
- logic flow
- entry point
- env variable
- error handling
- code convention
Add a description of your function and examples of use in the header comments.
Example:
/**
* Create a HTTP server
*
* import { serve } from "https://deno.land/std/http/server.ts";
* const body = "Hello World\n";
* const server = serve({ port: 8000 });
* for await (const req of server) {
* req.respond({ body });
* }
*/
export function serve(addr: string | HTTPOptions): Server {
if (typeof addr === "string") {
addr = _parseAddrFromStr(addr);
}
const listener = Deno.listen(addr);
return new Server(listener);
}- bussiness requirement
- use cases diagram
-
relation of tables and databases
-
Diagram that describe logic and flow for every step
- Why choose some libraries or modules
- Tell any technical changes
You can put those information in the release
Example: https://github.com/denoland/deno/releases