Skip to content

connectsoft.dev Domain Strategy

This document defines the strategy for connectsoft.dev as the engineering / docs / developer portal, and explains how it relates to the MkDocs documentation site and dev-facing APIs/SDKs. It is written for developers, DevOps, integrators, and documentation teams.

connectsoft.dev is where developers, DevOps, and integrators go for hands-on technical information. It hosts MkDocs-based docs, API references, SDKs, and code examples.

Important

Canonical Domain: connectsoft.dev is the canonical domain for developer documentation. All developer-facing content, APIs, SDKs, and technical resources should be accessible via .dev domain.

Role of connectsoft.dev

connectsoft.dev is the developer portal and technical resource center. It provides:

  • Technical Documentation - Comprehensive technical docs for Factory, platforms, templates, libraries
  • API References - Swagger/OpenAPI specs, API documentation, integration guides
  • SDKs and Code Examples - SDK documentation, code samples, tutorials
  • Developer Tools - Playgrounds, sandboxes, testing tools (future)

Key Characteristics: - Developer-First - Technical, precise, helpful - Comprehensive - Complete technical reference - Example-Rich - Lots of code examples and tutorials - Community-Oriented - Open to contributions and feedback

See: Documentation Style Guide for documentation standards.

Developer-Facing Content

Content Types

  • ConnectSoft AI Factory Dev/Ops Docs - Factory usage, agent configuration, execution flows
  • Platform Reference Docs - Identity, Audit, Config, Bot platform APIs and integration guides
  • Sample Code & SDKs - Code examples, SDK documentation, integration patterns
  • Integration Guides - Step-by-step guides for integrating with ConnectSoft platforms
  • Changelogs & Release Notes - Version history, breaking changes, migration guides
  • Templates & Libraries - Template documentation, library references, usage examples

See: Getting Started with Factory for Factory quickstart.

See: Getting Started with Platforms for platform quickstart.

See: Templates Overview for template documentation.

Integration with Documentation and APIs

MkDocs Site Location

Options: - docs.connectsoft.dev - Full MkDocs site (recommended) - connectsoft.dev/docs - Alternative path-based approach

Content Structure: - Factory documentation (agents, execution flows, principles) - Platform documentation (Identity, Audit, Config, Bot) - Templates & libraries documentation - Guides and tutorials - API reference - Changelog and roadmap

See: This internal documentation site (ConnectSoft.CompanyDocumentation) serves as the source for public-facing .dev documentation.

API References Location

Options: - api.connectsoft.dev - Unified API reference explorer - api.{product}.connectsoft.dev - Product-specific API references (e.g., api.identity.connectsoft.dev)

Content: - OpenAPI/Swagger specifications - REST API documentation - gRPC API documentation (if applicable) - Authentication and authorization guides - Rate limiting and usage policies

See: API Reference Overview for API documentation.

Tip

Cross-Linking Best Practice: .ai and .io should link developer calls-to-action straight into .dev. For example, "Developer docs → connectsoft.dev" or "API reference → api.connectsoft.dev". This ensures developers can quickly access technical resources.

Relationship to Repos and Tooling

Git Hosting

Azure DevOps: - Private repos for ConnectSoft code - Public repos for templates and libraries (if applicable) - Documentation repos (this repo)

GitHub (if applicable): - Public templates and libraries - Sample code and examples - Open-source contributions

Developer Flows

Flow 1: See Docs → Use SDK/API 1. Developer reads docs on .dev 2. Reviews API reference and SDK documentation 3. Downloads SDK or uses API directly 4. Integrates into their application

Flow 2: Contribute → Update Docs 1. Developer contributes code or templates 2. Documentation updated in repo 3. Docs published to .dev via CI/CD 4. Changes visible to all developers

Note: .dev references repos (read-only), but doesn't provide direct linking to private repo details. Public repos can be linked directly.

Top-Level Navigation

Sections: - Getting Started - Quick starts, tutorials, first steps - Factory - Factory documentation, agents, execution flows - Platforms - Identity, Audit, Config, Bot platform docs - Templates & Libraries - Template and library documentation - APIs & SDKs - API references, SDK documentation - Guides - Integration guides, tutorials, examples - Reference - Glossary, FAQ, changelog

Information Architecture

Factory Section: - Overview and architecture - Agent system and execution flow - Templates and libraries - Getting started guides

Platforms Section: - Platform overviews - API references - Integration guides - Code examples

Templates & Libraries Section: - Template catalog - Library references - Usage examples - Contribution guidelines

See: Factory Overview for Factory content structure.

See: Product Portfolio - Platforms for platform content structure.

Note

Internal-Only Docs: Internal-only documentation might live in private sub-paths or require authentication. Public .dev content should be accessible without authentication, while internal docs can be protected.

Guardrails and Non-Goals

What .dev Is Not

  • Not a General Marketing Site - That's .ai (strategic content) and .io (product marketing)
  • Not a Place for Localized Marketing - That's .co.il (Hebrew, local presence)
  • Not Customer-Facing Commercial Content - That's .io (product pages, pricing)

Content Guidelines

Do Include: - Technical documentation - API references and SDKs - Code examples and tutorials - Integration guides - Developer tools and playgrounds

Don't Include: - Marketing copy and sales content - Pricing and commercial information - Localized marketing content - Non-technical content

See: Documentation Style Guide for documentation standards.