Introduction
Last updated
Was this helpful?
Last updated
Was this helpful?
Production ready documentation is documentation that can be trusted to support a product running production traffic. This means the documentation is complete, up-to-date, and readily available. The documentation includes all the relevant and essential information necessary to understand the product.
Good documentation increases developer productivity, helps resolve issues faster, and creates a shared understanding of the product. This is because product ready documentation adopts a "self-service" mindset, where the documentation provides all the information for a person to solve their own problems just by reading the documentation.
While we seek to write maintainable, easy to read code, "there is no such thing as self-documenting code. While well-written code can tell you what it does, no programming language ... can tell you why it does it. This is why all software needs documentation beyond the code itself." (Brikman, Terraform Up & Running: Writing Infrastructure as Code, p. 154-155)
Comments Are Not Documentation
While comments are an essential piece of well written code, they are not production ready documentation. We don't want people to have to checkout and search through code to understand the product.
To assist in creation of production ready documentation, this was created as a self service tool. To get started, follow these steps:
Install the gitbook-cli.
Clone the prod-ready-docs git repository.
Copy /docs
and book.json
from the cloned repository to the top level directory of your project. To keep your existing README.md
as the introduction, instead of writing a new one, link it to docs/README.md
.
Run gitbook serve
and open to see live edits of the documentation.
Read each page's description and update the markdown file to document your project.
Update the table of contents in the SUMMARY.md
or add pages as needed.
Run gitbook serve
to build the static site to host or distribute. Or generate a PDF or eBook by following .
Include Documentation in Version Control
By including the /docs in the project, the documentation is now in version control. Because the documentation is plain text and lives with the source code, this allows documentation to be updated in parallel to code changes, easily
diff
ed, and results in the documention being versioned and tagged with the source code.