Let's Treat Docs Like Code
Treating documentation like code involves using tools like GitHub, automation, and static site generators. Importance of learning these tools, best practices for efficient writing, protecting branches, case studies, and resources are discussed. Insights on building documentation sites are provided.
Read original article
The article discusses treating documentation like code by using tools such as version control (GitHub) and automation (CICD) with static site generators (SSG). It provides a quick start guide on creating a GitHub account, setting up a repository, and publishing content on a web landing page. The importance of learning tools like GitHub and static site generators is emphasized, along with best practices for writing documentation efficiently. Additionally, it mentions protecting branches for team merges and publishing. The article also references various case studies and resources related to adopting Docs-as-Code, setting up Techdocs, survey results on learning docs-like-code techniques, and tips for maintaining a long-term relationship with docs as code systems. Lastly, it includes insights on building documentation sites using platforms like platformOS and using GitHub Pages with Python Sphinx for developer docs.
Related
Software Engineering Practices (2022)
Gergely Orosz sparked a Twitter discussion on software engineering practices. Simon Willison elaborated on key practices in a blog post, emphasizing documentation, test data creation, database migrations, templates, code formatting, environment setup automation, and preview environments. Willison highlights the productivity and quality benefits of investing in these practices and recommends tools like Docker, Gitpod, and Codespaces for implementation.
Git Workflows for API Technical Writers
Technical writers encounter challenges in maintaining API documentation aligned with evolving designs. Git workflows provide version control and collaboration benefits. Strategies like merging copy improvements, code annotations, and OpenAPI overlays enhance documentation quality. Involving writers in API design ensures user-centric content. Storing docs in separate repositories can resolve Git conflicts.
Writing HTML by hand is easier than debugging your static site generator
The blog author discusses challenges of static site generators versus manual HTML coding, citing setup complexities and advocating for simplicity, stability, and control in website management. Emphasizes static data benefits.
Simple GitHub Actions Techniques
Denis Palnitsky's Medium article explores advanced GitHub Actions techniques like caching, reusable workflows, self-hosted runners, third-party managed runners, GitHub Container Registry, and local workflow debugging with Act. These strategies aim to enhance workflow efficiency and cost-effectiveness.
Docs as code (2017)
Documentation as Code (Docs as Code) aligns documentation creation with coding practices, emphasizing collaboration, integration with development, and tool consistency. Write the Docs community advocates this approach through talks, successful industry examples, recommended books, and an open-source toolchain for effective implementation.
2 commentsDocs as code (2017)
Related
Software Engineering Practices (2022)
Gergely Orosz sparked a Twitter discussion on software engineering practices. Simon Willison elaborated on key practices in a blog post, emphasizing documentation, test data creation, database migrations, templates, code formatting, environment setup automation, and preview environments. Willison highlights the productivity and quality benefits of investing in these practices and recommends tools like Docker, Gitpod, and Codespaces for implementation.
Git Workflows for API Technical Writers
Technical writers encounter challenges in maintaining API documentation aligned with evolving designs. Git workflows provide version control and collaboration benefits. Strategies like merging copy improvements, code annotations, and OpenAPI overlays enhance documentation quality. Involving writers in API design ensures user-centric content. Storing docs in separate repositories can resolve Git conflicts.
Writing HTML by hand is easier than debugging your static site generator
The blog author discusses challenges of static site generators versus manual HTML coding, citing setup complexities and advocating for simplicity, stability, and control in website management. Emphasizes static data benefits.
Simple GitHub Actions Techniques
Denis Palnitsky's Medium article explores advanced GitHub Actions techniques like caching, reusable workflows, self-hosted runners, third-party managed runners, GitHub Container Registry, and local workflow debugging with Act. These strategies aim to enhance workflow efficiency and cost-effectiveness.
Docs as code (2017)
Documentation as Code (Docs as Code) aligns documentation creation with coding practices, emphasizing collaboration, integration with development, and tool consistency. Write the Docs community advocates this approach through talks, successful industry examples, recommended books, and an open-source toolchain for effective implementation.