cogdocs

Capabilities

CogDocs enables agents to understand and implement a complete technical documentation system that combines content strategy, style guidelines, and AI-powered authoring tools. Agents can help teams create consistent, discoverable documentation across multiple content types, manage global localization workflows, analyze content performance, and leverage AI assistance for efficient content production while maintaining quality standards.

Skills

Content Model & Information Architecture

• Define and organize documentation using six core content types: concept (understand), reference (lookup), procedure (do), tutorial (learn), quickstart (get going), and troubleshooting (fix)
• Structure content hierarchically using collections, categories, map topics, and articles
• Create map topics that group related articles using Mintlify cards and columns
• Organize content consistently from broad to specific: concepts → reference → procedures → troubleshooting
• Implement content reuse through snippets and variables to maintain consistency across multiple articles

Content Type Specialization

• Concept articles: High-level overviews helping users understand features and their importance
• Reference content: Detailed lookup information for queries, syntax, specifications, and technical details
• Procedures: Step-by-step task completion guides with clear action-oriented instructions
• Quickstarts: Focused 5-minute guides for initial setup or simple tasks with minimal prerequisites
• Tutorials: End-to-end workflow guides with conversational tone for learning and real-world problem solving
• Troubleshooting: Error documentation and common problem solutions integrated into guides
• Release notes: Structured updates grouped by predefined types for version planning

Metadata & Content Classification

• Apply required metadata fields: title (max 80 chars), description (75-300 chars), audience, content-type, article-type, experience-level
• Target content to specific audiences: businessUser, administrator, dataEngineer, developer, aiEngineer, appMaker, dataAnalyst, dataScientist, securityEngineer, solutionArchitect, partner, businessDecisionMaker
• Set experience levels: 100 (beginner), 200 (intermediate), 300 (advanced)
• Define lifecycle stages: investigate, verify, setup, use, support, transform
• Mark content for localization with to-L10N: true flag

Style & Voice Guidelines

• Write in American English with casual, friendly tone using everyday language
• Focus on user intent and task completion rather than technical lectures
• Use concise, active voice avoiding wordiness and excessive qualifiers
• Employ evidence-based communication with specific data and examples
• Show empathy and acknowledge user frustrations honestly
• Maintain consistency with Microsoft Style Guide principles
• Use first-person active voice for agent communication (“I found”, “I’m seeing”)

Quality Assurance

• Apply quality criteria across three dimensions: easy to use (task orientation, accuracy, completeness), easy to understand (clarity, concreteness, style), easy to find (organization, retrievability, visual effectiveness)
• Validate task orientation, accuracy, and completeness before publishing
• Ensure clarity through focused meaning, eliminated wordiness, and consistent terminology
• Verify content organization, retrievability through search optimization, and visual effectiveness
• Use quality checklists to validate technical accuracy and user workflow testing

Visual Elements & Graphics

• Create screenshots (PNG, 144 dpi, max 250 KB) to complement text when UI elements are hard to find
• Use SnagIt for screenshot capture with Cognite Docs theme for highlighting (dark orange #BC4C00)
• Create illustrations (SVG format) using Diagrams.net for processes and concepts not tied to specific UI
• Generate diagrams using Mermaid for flowcharts and entity-relationship diagrams
• Embed videos sparingly alongside written text for enhanced user experience
• Store all images in CDN with descriptive file names and version control

Mintlify Components & Formatting

• Use accordions for glossaries, troubleshooting, and additional information
• Apply callouts (Info, Note, Tip, Check, Warning, Danger) sparingly for critical information
• Create landing pages with cards and columns for collection and category overviews
• Use CodeGroup for tabbed code examples in multiple languages
• Implement Frames to center and caption illustrations and screenshots
• Structure sequential tasks with Steps component for procedures, tutorials, and quickstarts
• Organize related content with Tabs for platform-specific or approach-specific variations
• Use tables for multi-attribute data comparison and equipment listings
• Apply inline code for equipment IDs, values, file names, and commands

AI-Powered Content Creation with Cursor

• Leverage Cursor AI editor with integrated CogDocs rules for context-aware assistance
• Use content-type-specific rules (conceptual-content-type.mdc, procedure-content-type.mdc) for proper structure
• Apply the 7-step workflow: plan, research, outline, draft, refine, review, publish
• Request content-type rules using @rules/[content-type]-content-type for specialized guidance
• Use comprehensive prompt library for planning, writing, refining, and quality assurance
• Leverage AI for structure and style while maintaining human validation for technical accuracy

Industrial AI Agent Voice & Formatting

• Communicate with evidence-based language citing specific data (sensor readings, equipment IDs, timestamps)
• Use decision-ready formatting with bold for critical values, clear headings, and structured data
• Employ zero-ambiguity language with specific, measurable terms instead of vague descriptions
• Lead responses with direct answers immediately, avoiding context or preamble
• Use first-person conversational voice (“I found”, “I’m seeing”) for natural colleague-like communication
• Format technical data in code blocks with proper alignment for easy scanning
• Present multi-attribute data in tables for efficient comparison
• Keep initial responses short (2-4 sentences), explicitly offering additional detail
• Adapt response structure to workflow phase: triage (prioritize), execution (action-focused), handoff (summary)

Progressive Disclosure & Context Engineering

• Layer information based on user engagement: core answer → context → deep detail → related insights
• Validate data quality before reporting: check timestamp freshness, sensor health, unit certainty
• Assess operational safety: avoid hallucinating thresholds, state scope boundaries, require confirmation for write-actions
• Provide transparency through source attribution and confidence calibration
• Recognize engagement signals (follow-up questions, technical language, continued conversation)
• Adapt information density to urgency: emergency (minimal), routine (conversational), planning (detailed)
• Reference conversation history and anticipate next steps

Internationalization & Localization (I18N/L10N)

• Write content with internationalization best practices for global audiences
• Mark content for translation with to-L10N: true in YAML frontmatter
• Use Python scripts to package content files for localization handoff
• Extract navigation strings for translation into separate CSV files
• Synchronize localization cycles with major software releases (typically quarterly)
• Manage translated content in language-specific folders (de/, fr/, etc.) mirroring English structure
• Support multiple language variants while maintaining single source of truth

Content Analytics & Performance Optimization

• Analyze content performance using Mixpanel, Mintlify, and Google Search Console
• Identify high-traffic, low-engagement pages needing content improvements
• Document search queries returning poor results or high bounce rates
• Create content gap analysis based on unsuccessful searches and AI queries
• Recommend content format improvements based on user behavior patterns
• Propose information architecture changes to improve discoverability
• Establish automated reporting for key documentation metrics
• Create monthly dashboards tracking search performance, traffic patterns, and AI effectiveness

Automated Changelog Management

• Use PR labels to automatically generate weekly changelogs
• Organize releases by predefined types for consistent categorization
• Collaborate with product managers and engineers to source and edit updates
• Publish version-specific release notes for change-controlled environments
• Help administrators plan upgrades and end users prepare for new features

Workflows

Creating a New Concept Article

1. Identify the feature or topic requiring explanation
2. Define target audience and their knowledge level
3. Create YAML frontmatter with metadata (title, description, audience, content-type: concept)
4. Write introduction explaining what the feature is and why it matters
5. Structure content from broad to specific using clear headings
6. Include relevant examples and use cases
7. Add cross-references to related procedures and reference materials
8. Review for clarity, accuracy, and completeness using quality checklist
9. Commit to repository and trigger automatic Mintlify deployment

Developing a Procedure Article

1. Define the specific task users will complete end-to-end
2. Identify prerequisites and assumptions about user knowledge
3. Create YAML frontmatter with metadata (content-type: procedure)
4. Write clear introduction stating the task and expected outcome
5. Use Steps component for sequential actions with action-oriented titles
6. Include screenshots only when UI elements are hard to find
7. Add troubleshooting section for common errors
8. Provide context and explanations within steps, not before
9. Test the procedure by following steps exactly as written
10. Validate technical accuracy with subject matter experts

Building a Quickstart Guide

1. Identify a focused, discrete task achievable in 5 minutes
2. Determine minimal prerequisites needed for success
3. Create YAML frontmatter with metadata (content-type: quickstart)
4. Write energetic introduction promising specific, valuable outcome
5. Limit to 3-5 major steps maximum using most direct path
6. Include immediate feedback/verification for each step
7. Link to detailed explanations rather than including them
8. Add success validation confirming promised outcome achieved
9. Provide 2-3 strategic next steps building on foundation
10. Test completion time with actual users

Implementing Content Localization

1. Mark all content for translation with to-L10N: true in frontmatter
2. Write content following internationalization best practices
3. Run python scripts/copy-l10n-files.py to create i18n/en-us/ folder
4. Extract navigation strings using python scripts/extract_navigation-l10n.py
5. Package content files and CSV files for translation vendor
6. Receive translated content in language-specific folders
7. Build and QA localized documentation
8. Publish translated versions alongside English content
9. Maintain single source of truth in English with synchronized updates

Optimizing Content Based on Analytics

1. Set up automated reports in Mixpanel for key metrics
2. Create monthly dashboards showing search performance and traffic patterns
3. Identify high-traffic, low-engagement pages
4. Document search queries with poor results
5. Analyze AI assistant query patterns for content gaps
6. Create prioritized improvement list based on impact and effort
7. Recommend content format changes (tutorials, quickstarts, troubleshooting)
8. Propose information architecture improvements
9. Implement changes and monitor impact
10. Schedule quarterly deep dives for strategic planning

Writing with Cursor AI Assistance

1. Open Cursor editor with repository access
2. Create new article file with appropriate naming convention
3. Request content-type rule: @rules/[content-type]-content-type
4. Use planning prompts to create detailed content outline
5. Request research prompts for gathering information
6. Use drafting prompts to generate initial content
7. Apply refinement prompts to improve clarity and conciseness
8. Run Vale and Grammarly for style and grammar checking
9. Review AI-generated content for technical accuracy
10. Commit changes and create pull request for review

Integration

CogDocs integrates with multiple tools and systems:

• Mintlify: Publishing platform handling docs-as-code workflow, GitHub integration, automated deployment, and AI features (natural language search, MCP server generation)
• Cursor: AI-powered code editor with integrated CogDocs rules for context-aware writing assistance
• GitHub: Version control and collaboration with pull requests, reviews, and automated publishing triggers
• Mixpanel: Analytics platform for tracking content performance, search patterns, and user behavior
• Google Search Console: SEO monitoring and search query analysis
• Diagrams.net: Illustration and diagram creation tool
• SnagIt: Screenshot capture and annotation tool
• Translation vendors: Localization services for multi-language content management

Context

CogDocs represents a complete documentation system designed for technical teams managing complex product documentation at scale. The framework emphasizes consistency through codified standards, discoverability through structured metadata and information architecture, and maintainability through version control and automated workflows.

The system recognizes that different users need different types of content: conceptual articles for understanding, reference materials for lookup, procedures for task completion, quickstarts for rapid onboarding, tutorials for learning, and troubleshooting guides for problem resolution. Each content type has specific structural patterns and purposes.

Quality is built into the system through metadata standards, style guidelines, and quality checklists that ensure content is easy to use, easy to understand, and easy to find. The integration with Cursor AI enables efficient content production while maintaining human oversight of technical accuracy.

For industrial and technical audiences, CogDocs emphasizes evidence-based communication with specific data, decision-ready formatting, and progressive disclosure of information. Agents should lead with direct answers, use structured formatting for technical data, and adapt response depth to user engagement and workflow phase.

The framework supports global audiences through internationalization and localization processes synchronized with product releases, ensuring documentation remains current across multiple languages while maintaining a single source of truth in English.

For additional documentation and navigation, see: https://cogdocs.mintlify.app/llms.txt