Skip to content

Latest commit

 

History

History
73 lines (64 loc) · 2.95 KB

README.md

File metadata and controls

73 lines (64 loc) · 2.95 KB
Raw

The /docs directory stores project documentations, runbooks and any other kind of textual reference. These are often written in formats like Markdown and, depending on the project scope and technology stack, require a preprocessor. Note that documentations built with web based tools like static site generators (e.g. Gatsby, Next.js or Hugo) should be placed as own package in the /web directory.

Directory Structure

The layout always depends on the individual use case(s) of the project and when hosted on platforms like GitHub Pages or GitLab Pages. A common practice is to store documentations in separate repositories, often in combination with static site generator configurations, for example the official Kubernetes website or Knative documentations.

Example

Given the example of the /api directory the structure for some common configurations could be created as follows:

docs
└─ notes
   ├─ adr
   │  ├─ api
   │  ├─ architecture
   │  ├─ cli
   │  ├─ engineering
   │  ├─ sdk
   │  └─ specification
   ├─ api
   ├─ guides
   │  ├─ development
   │  ├─ roadmap
   │  └─ runbook
   └─ maintenance
      ├─ release
      │  └─ notes
      ├─ runbook
      └─ support

References

Next to the experience with own projects and golang-standards/project-layout, many other large, production-grade and well-known projects of the Go ecosystem have been used as references: