Contributing to Documentation¶

This guide covers standards and best practices for contributing to the openstan user guide. All documentation pages must follow these principles to maintain consistency, readability, and search engine visibility.

Quick Checklist¶

Before submitting a documentation change, ensure:

• [ ] Frontmatter includes a page-specific description field (150–160 characters)
• [ ] description is unique and summarizes the page's value, not the site description
• [ ] Page has a single H1 heading (the title)
• [ ] Internal links use relative paths (e.g., [link](../guides/export-data.md))
• [ ] All images have descriptive alt text and follow theme conventions (#only-light / #only-dark for theme-variant images)
• [ ] Code examples are clear, tested, and include language hints (```python)
• [ ] Page is linked from at least one related page (internal linking for crawlability)

Frontmatter & SEO¶

Frontmatter Structure¶

Every documentation page must include frontmatter with a description field:

---
description: "Import 12 months of bank statement PDFs, separate business from personal transactions, and export clean data for your Self Assessment tax return. 100% offline."
---

# Page Title

Description Field Requirements¶

The description field is critical for SEO — it appears in: - Google Search results (SERP snippets) - Open Graph meta tags (social media previews) - Twitter Card summaries (Twitter/X)

Guidelines:

• Length: 150–160 characters (Google shows 150–160 chars in search results)
• Uniqueness: Must be specific to the page, not the generic site description
• Search intent: Begin with action verbs or clear value propositions:
• ✅ "Import 12 months of bank statement PDFs, separate business from personal..."
• ✅ "Step-by-step guide to creating your first project, importing bank statements..."
• ❌ "User guide for openstan — a desktop application..." (generic site description)
• Keyword inclusion: Naturally include 1–2 target keywords (not stuffed):
• ✅ "Export committed transaction data to Excel, CSV, or JSON..."
• ❌ "Export export export to Excel CSV JSON..."
• Avoid: Periods, promotional language ("Best!", "Amazing!"), or brand mentions unless necessary

Examples:

Page Structure¶

Headings (H1, H2, H3)¶

• H1 (one per page): Page title, always auto-generated from frontmatter or Markdown H1
• H2 (sections): Major topic divisions
• Nest logically; avoid skipping levels (H1 → H2 → H3, not H1 → H3)
• Keep to 2–5 per page for readability
• H3 (subsections): Detail within major sections
• Use sparingly; too many indicates content should be split across pages

Example structure:

# Main Feature Title

## Overview / When to Use This

## Key Concepts or Prerequisites

### Sub-topic A

### Sub-topic B

## Step-by-Step Guide (if applicable)

## Common Issues & Troubleshooting

## Related Topics

Content Flow¶

1. Opening paragraph (2–3 sentences):
2. Restate what the page is about (users skim)
3. Mention search keywords naturally

4. Link to related pages if needed

5. Body sections:

6. Use H2 for major topics
7. Start sections with brief intent statements

8. Include examples, screenshots, or code where helpful

9. Closing:

10. Optional: "See Also" or "Related Topics" section with 3–5 internal links
11. Links must use relative paths and point to .md files (MkDocs converts to URLs)

Internal Linking¶

Internal links help Google crawl and understand your site structure. They also improve user navigation.

Guidelines¶

• Link frequently (3–5 links per ~1,000 words is typical)
• Use descriptive anchor text: ❌ "Click here" → ✅ "Export Data" or "See the export guide"
• Link to related pages:
• Use-case pages should link to relevant screen/feature pages
• Screen pages should link back to use cases that use them
• Sequential guides should link forward/backward
• Use relative paths: [Export Data](../guides/export-data.md) — MkDocs converts to URLs automatically
• Avoid linking to the same page (e.g., don't link to /guides/export-data/ from within that same page)

Example — Page Linking Map:

/use-cases/self-assessment/
├─ Links to: /guides/export-data/ (to export for tax)
├─ Links to: /guides/run-reports/ (to build custom reports)
├─ Links to: ../index.md (back to all use cases)
└─ Links to: ../installation.md (getting started)

Images & Screenshots¶

Best Practices¶

• Alt text: Every image must have descriptive alt text (![description](path))
• ✅ "Project Management panel showing statement queue with 3 PDFs"

• ❌ "screenshot" or leaving empty

• Theme variants: For light/dark theme screenshots, use fragment identifiers:

  ![Alt text — light](assets/screenshots/foo.png#only-light)
  ![Alt text — dark](assets/screenshots/dark/foo.png#only-dark)
  

• Light variants go in assets/screenshots/
• Dark variants go in assets/screenshots/dark/

• Zensical CSS hides the non-matching variant per user's theme

• File size: Optimize images before committing (compression, reasonable dimensions)

Code Examples¶

• Use language-specific code blocks:

  # Good
  def my_function():
      pass
  

# Avoid (no language hint)
def my_function():

• Testability: Examples should be runnable (or clearly show what a user would do)
• Comments: Use inline comments to explain non-obvious logic
• Syntax highlighting: Ensure the language is specified for proper highlighting

Writing Style¶

Tone¶

• Clear, direct, and helpful
• Avoid jargon; explain technical terms on first use
• Write for UK English (e.g., "analyse" not "analyze")

Common Patterns¶

• Instructional: "To import statements, click Import (Ctrl+I)..."
• Conceptual: "The Export Data panel separates committed transactions from queued imports..."
• Cautionary: "⚠️ Deleting a project cannot be undone."

Formatting¶

• Bold for UI buttons/menu items: "Click File → Export"
• Code font for file paths, commands, config keys: project.db, uv run openstan
• Monospace blocks for terminal output or structured data
• Admonitions (if supported) for notes/warnings:

  !!! note "Important"
      This is a note.
  
  !!! warning "Be careful"
      This is a warning.
  

SEO Checklist Per Page¶

Use this when adding or updating a page:

Examples of Well-Structured Pages¶

Excellent¶

• /use-cases/self-assessment.md — specific description, clear sections, internal links
• /guides/export-data.md — action-oriented, screenshots, step-by-step instructions
• /installation.md — platform-specific guidance, linked from multiple places

Needs Improvement¶

• docs/guides/about.md — generic description, minimal content, no internal links
• docs/feedback.md — single paragraph, missing H2 sections

Adding a New Page¶

Steps¶

1. Create the file in the appropriate directory:
2. Use-case guides → docs/use-cases/
3. Feature/screen guides → docs/guides/

4. General info → docs/

5. Add to mkdocs.yml nav:

   nav:
     - Screens:
         - Export Data: guides/export-data.md
         - New Feature: guides/new-feature.md  # ← add here
   

6. Write with frontmatter:

   ---
   description: "150–160 character unique summary of page content."
   ---
   
   # Page Title
   
   Opening paragraph...
   

7. Include internal links:

8. Link from related pages back to your new page

9. Link from your new page to 3–5 existing related pages

10. Test before committing:

    uv run zensical build
    # Check site/your-new-page/index.html for correct og:description
    

11. Verify sitemap:

    • Run uv run zensical build and check site/sitemap.xml
    • Your new page should appear with <url>https://openstan.org/your-new-page/</url>

Documenting Logging Features¶

When updating documentation to reference logging features or writing new pages that involve logging:

Page-Level Guidance¶

• Link to the Logging Guide: When a page describes operations that generate logs, link to guides/logging.md for detailed information
• Use consistent terminology:
• "App log" and "Project log" (capitalized, with article)
• "verbose mode" (lowercase) for the user-facing feature
• "DEBUG logging" for technical/developer context
• "normal mode" for INFO-level logging

Cross-Linking Strategy¶

• Troubleshooting pages should link to Logging & Debugging Guide for diagnostic steps
• Feature pages (Import, Export, Anonymise) should mention checking the Project Log if issues occur
• Admin screen documentation should explain View Logs and Logging Settings (already done in guides/admin.md)

Example Links¶

# Good: Linking to logging guide from a feature page
If the import fails, enable verbose mode for detailed diagnostics. 
See [Enabling Verbose Mode](logging.md#enabling-verbose-mode-debug-logging).

# Good: Linking from troubleshooting to logging guide
For detailed information about logs, see the 
[Logging & Debugging Guide](guides/logging.md).

# Good: Mentioning logging in an error description
Check the [Project Log](guides/logging.md#viewing-logs) to see what went wrong.

Screenshots & Logging UI¶

• If Admin dialog or log viewer UI changes, update screenshots in docs/assets/screenshots/ and docs/assets/screenshots/dark/
• Use theme-variant syntax: #only-light and #only-dark fragments
• Include privacy warning context in any log viewer screenshots

Privacy Guidance¶

When documenting features that produce logs containing user data:

• Include a privacy notice: "Logs may contain sensitive bank account information"
• Explain data redaction when sharing logs with support
• Link to Privacy Policy where appropriate
• Provide examples of safe redaction (see guides/logging.md#sharing-logs-with-support)

SEO Considerations¶

Logging-related keywords to naturally include in descriptions and content:

• "Debugging" (diagnostic/troubleshooting context)
• "Verbose mode" (feature name)
• "Logs" or "application logs" (file type)
• "Troubleshooting" (use case)
• "Support" (when to share logs)

Maintenance¶

• Review quarterly: Check for outdated information, broken links, or screenshots
• Update descriptions when: Page content significantly changes, new keywords are targeted
• Test before deployment: Always run uv run zensical build locally and inspect the generated HTML

Questions?¶

Refer to AGENTS.md for project architecture and tech stack details. This guide covers documentation contribution standards only.

Related Topics¶

• Community & Support – Connect with other contributors and users
• About Screen – Attribution and license information
• Privacy Policy – Data handling standards
• GitHub Repository – View source code and open issues