Patria Tech Docs

Patria Tech Docs

How to contribute

How to Contribute

Documentation in patria-tech-docs-kb is maintained as code in Git. Any team member can create and edit pages using Obsidian and GitHub Desktop, with automatic publishing via Quartz on every commit to main.

Initial Setup

1. Create a GitHub account and request access

2. Install GitHub Desktop

  1. Download GitHub Desktop for your operating system
  2. Install and launch the application
  3. Sign in with your GitHub account
  4. Authorize the app to access your GitHub repositories

3. Clone the repository with GitHub Desktop

  1. Go to File → Clone Repository
  2. Click the URL tab
  3. Paste the repository URL: https://github.com/patria-investimentos/patria-tech-docs-kb.git
  4. Choose a local path on your computer (e.g., ~/Documents/patria-tech-docs-kb)
  5. Click Clone

4. Install and open Obsidian

  1. Download Obsidian for your operating system
  2. Install and launch the application
  3. Click Open folder as vault
  4. Navigate to the cloned repository folder and select it
  5. Trust the vault when prompted

Tip

Obsidian tip: Use the graph view (Ctrl+G / Cmd+G) to visualize connections between documents. The backlinks pane shows which pages reference the current document.

Contribution workflow

Step 1: Create or edit a document

  1. In Obsidian, navigate to the appropriate folder based on document type (see table below)
  2. Create a new file or edit an existing one
  3. Start with the required frontmatter (see section below)
  4. Follow the writing best practices and templates

Step 2: Save your changes

  • Obsidian auto-saves as you type — no manual save needed
  • Git will track all changes automatically

Step 3: Commit to main branch

  1. Open GitHub Desktop
  2. Click the Changes tab — you’ll see all modified files
  3. Review the changes in the preview pane
  4. Enter a commit message following the format: docs: add/update [description]
    • Examples: docs: add BigQuery runbook, docs: update ADR-001
  5. Click Commit to main
  6. Click Push origin to publish to GitHub

Step 4: Publishing (automatic)

  • The documentation site automatically rebuilds and deploys within minutes of your commit
  • View the published site at your team’s Quartz portal URL
  • No manual deployment steps needed

Where to create each document type

What to documentWhere to create
New systemCopy _templates/template-system.md → 06-systems/[system-name]/index.md
System runbookCopy _templates/template-runbook.md → 06-systems/[system-name]/runbooks/[procedure].md
Architecture decisionCopy _templates/template-adr.md → 02-architecture/adr/adr-NNN-short-title.md
PostmortemCopy _templates/template-postmortem.md → 08-support/postmortems/YYYY-MM-DD-title.md
Data catalog entryAdd entry to 07-data/catalog/datasets-[domain].md

Required frontmatter

Every .md file must start with exactly these 4 fields:

---
title: "Descriptive title here"
status: draft
tags: [Category, System, Technology]
updated: 2026-05-06
---

Field guide:

FieldPurposeExample
titleHuman-readable title (will display on published page)"BigQuery — Data Lake", "N8N automation platform"
statusPublication status: draft (internal only) or active (published)active
tagsCategory tags for organization (Title Case, comma-separated)[System, Data, GCP]
updatedLast update date in YYYY-MM-DD format2026-05-06

Naming conventions

  • Folders and files: kebab-case (e.g., private-equity.md, totvs-fluig/)
  • File titles (frontmatter): User-friendly, readable format (Title Case or sentence case)
    • Example: "BigQuery — Data Lake" or "ADR-001: Authentication with Entra ID"
  • Headings in content: Sentence case preferred (e.g., ## Overview)
  • ADRs: adr-NNN-short-title.md with sequential numbering
  • Postmortems: YYYY-MM-DD-short-title.md

Writing best practices

Use admonitions for emphasis

> [!warning]
> 
> **Title:** Important warning content here
 
> [!tip]
> 
> **Tip:** Helpful suggestion
 
> [!info]
> 
> **Info:** Additional context

Supported types: note, abstract, info, todo, tip, success, question, warning, failure, danger, bug, example, quote

Structure for clarity

  • Prefer lists and tables over long paragraphs
  • Use relative links between documents: [Link text](../../runbooks/system/procedure.md)
  • Avoid H4 headings; stick to H1–H3 and don’t skip heading levels

Add diagrams

Include Mermaid diagrams for architecture and flows:

flowchart LR
    A[System A] --> B[API Gateway] --> C[System B]

Updating a published document

  1. Open the document in Obsidian and make your changes
  2. Update the updated field to today’s date
  3. Commit to main via GitHub Desktop with message: docs: update [document name]
  4. The site rebuilds automatically

Questions?

  • Check 01-getting-started/contacts.md for team ownership and who to ask
  • Review existing documents in the repository to see examples of good structure

Backlinks