From b02965dfd6f1732f7f3f1243183bc77e6e6d8b6a Mon Sep 17 00:00:00 2001 From: Johnny Date: Thu, 6 Aug 2026 16:11:57 +0200 Subject: [PATCH 1/3] Added Mermaid diagram for Pipelines --- src/content/docs/tools/pipelines.md | 34 +++++++++++++++++++++++++++++ 1 file changed, 34 insertions(+) create mode 100644 src/content/docs/tools/pipelines.md diff --git a/src/content/docs/tools/pipelines.md b/src/content/docs/tools/pipelines.md new file mode 100644 index 0000000..a488f14 --- /dev/null +++ b/src/content/docs/tools/pipelines.md @@ -0,0 +1,34 @@ +--- +title: Pipelines +config: + theme: base + themeVariables: + primaryColor: "#4f3535" +description: Description on pipelines and workflows within this project. +--- + +Pipelines are being triggered during 'git push' or deployment. These are being constructed to prevent issues to occur and to catch common mistakes. + +```mermaid +flowchart TD + A[Git Push] --> B[Github] + + subgraph GHA[Github Actions] + C[Forbidden Words Checker] + D[Merge Conflict Checker] + E[Versioning] + end + + B --> C + B --> D + B --> E + + C --> F[Deployment] + D --> F + E --> F +``` + + +## Further reading + +- Read [about reference](https://diataxis.fr/reference/) in the Diátaxis framework From 11d3444353ff2718d3cef711e1155b90cd70ca91 Mon Sep 17 00:00:00 2001 From: Johnny Date: Thu, 6 Aug 2026 17:16:39 +0200 Subject: [PATCH 2/3] Pipeline error --- .github/workflows/deploy.yml | 1 + 1 file changed, 1 insertion(+) diff --git a/.github/workflows/deploy.yml b/.github/workflows/deploy.yml index 7d9df7c..3ececf3 100644 --- a/.github/workflows/deploy.yml +++ b/.github/workflows/deploy.yml @@ -32,6 +32,7 @@ jobs: deploy: needs: build runs-on: ubuntu-latest + timeout-minutes: 30 environment: name: github-pages url: ${{ steps.deployment.outputs.page_url }} From ea8d81567f00d51d7a07be5b2d3dd532f9dd0bc7 Mon Sep 17 00:00:00 2001 From: Johnny Date: Fri, 7 Aug 2026 10:09:08 +0200 Subject: [PATCH 3/3] Editorial update on docs-as-code --- src/content/docs/guides/example.mdx | 32 +++++++++++++++++------------ 1 file changed, 19 insertions(+), 13 deletions(-) diff --git a/src/content/docs/guides/example.mdx b/src/content/docs/guides/example.mdx index 8e0f789..6bca5a6 100644 --- a/src/content/docs/guides/example.mdx +++ b/src/content/docs/guides/example.mdx @@ -6,32 +6,38 @@ lang: 'en-uk' # What Is Docs-as-code? -
- -Docs-as-code is a technical writing environment where the technical writer uses the same tools as the software developers. When documenting softwares, this eases the reviewing process and increases the collaboration possibilities. +Docs-as-code is a documentation approach where technical writers and developers work in the same environment and use the same tools. By storing documentation in version control and writing in lightweight formats such as Markdown, teams gain a faster review process, clearer collaboration, and a workflow that aligns with modern software development.
## Benefits -When using Docs-as-code with Markdown compared with DITA, includes the following benefits: +Using a docs-as-code workflow with Markdown, compared to traditional DITA-based systems, provides several advantages: -* Smoother and faster reviewing process. -* Flexibility when working with information layout. -* Installing add-ons to make the documentation into a product. +* **Faster and more structured reviews** through pull requests and inline comments. +* **Flexible content layout** without rigid XML schemas. +* **Easy integration of add-ons** that transform documentation into a product. ### Add-ons To Integrate -The following add-ons are great extensions to the docs-as-code environment: +The following tools extend and enhance a docs-as-code environment: * Litlyx - * Litlyx is a Traffic Analytics site from Italy, Europe. The installation process is quick and the product is GDPR compliant. See [Litlyx webpage](https://litlyx.com/) for more information. + * A lightweight, GDPR-compliant analytics tool that provides traffic insights for documentation portals. See [Litlyx webpage](https://litlyx.com/) for more information. * Swagger - * Swagger is an API preview documentation tool. The tool provides example requests and example of a return object. See [Swagger webpage](https://swagger.io/) for more information. + * An interactive API documentation tool that displays example requests, response schemas, and live testing. See [Swagger webpage](https://swagger.io/) for more information. * GitLens - * GitLens is a git viewing tool. This tool visualizes the git branches and provides insights to the git history. - * GitLens is especially helpful when new to git. See [GitLens wepage](https://www.gitkraken.com/gitlens) for more information. + * A Git visualization extension for VS Code that helps contributors understand commit history, branching, and collaboration patterns. See [GitLens wepage](https://www.gitkraken.com/gitlens) for more information. + +## Docs-as-code VS DITA + +Docs-as-code is often preferred over DITA in the following situations: + +- **Software documentation**, where writers benefit from using the same tools as developers. +- **Cost efficiency**, avoiding licensing fees associated with DITA-based systems. +- **Flexibility**, allowing writers to structure content without strict XML constraints. +- **Integration**, enabling documentation to fit naturally into the IT ecosystem and CI/CD pipelines. ## Further reading -- Read [about how-to guides](https://diataxis.fr/how-to-guides/) in the Diátaxis framework +- Read [Docs-as-code](https://www.writethedocs.org/guide/docs-as-code/) from Write The Docs for more information.