Contributing to Traylinx Documentation¶

Thank you for your interest in improving the Knowledge Hub! This guide explains how to contribute effectively.

Getting Started¶

Prerequisites¶

Git installed locally
Python 3.8+ (for local preview)
Familiarity with Markdown

Local Development¶

Clone the repository

git clone https://github.com/traylinx/traylinx-docs-hub.git
cd traylinx-docs-hub

Install dependencies
```
pip install -r requirements.txt
```
Start the local server
```
mkdocs serve
```
Open http://localhost:8000 in your browser

Making Changes¶

Branch Naming¶

Use descriptive branch names:

Type	Pattern	Example
New content	`docs/feature-name`	`docs/add-sdk-quickstart`
Fixes	`fix/issue-description`	`fix/broken-links-tutorial`
Updates	`update/section-name`	`update/api-reference`

Commit Messages¶

Write clear, descriptive commit messages:

docs: add Python SDK quickstart guide

- Add installation instructions
- Include authentication examples
- Add troubleshooting section

Pull Request Process¶

Create a feature branch from main
Make your changes
Run the accessibility audit: python scripts/accessibility_audit.py
Test locally with mkdocs serve
Submit a pull request
Wait for review and address feedback

Content Guidelines¶

File Structure¶

docs/
├── index.md              # Homepage
├── sdks/                 # SDK documentation
├── architecture/         # System architecture
├── FAQ/                  # How-to guides
├── for-agents/           # AI agent resources
└── stylesheets/          # Custom CSS

Frontmatter¶

Every page requires frontmatter:

---
title: Page Title
description: Brief description for SEO (max 160 chars)
---

Writing Style¶

Use second person ("you") for instructions
Use active voice over passive
Keep sentences concise
Define technical terms on first use
Include code examples where helpful

See the Style Guide for detailed standards.

Quality Checks¶

Before submitting, run these checks:

# Build the site (catches broken links)
mkdocs build --strict

# Run accessibility audit
python scripts/accessibility_audit.py

# Check for stale content
python scripts/stale_content_detector.py

Getting Help¶

Questions: Open a GitHub Discussion
Bug reports: Create a GitHub Issue
Feature requests: Create a GitHub Issue with the enhancement label

Code of Conduct¶

Be respectful and inclusive
Focus on constructive feedback
Help others learn and grow

Thank you for contributing! 🚀