Quick Navigation

• Overview
• Documentation Types
• Visibility Rules
• Organization
• File Formats
• Configuration
• Best Practices
• Debugging
• Future Enhancements

Overview

The Comserv documentation system provides a structured way to organize and access documentation for different sites, roles, and modules. This comprehensive guide explains how the documentation system works, including visibility rules, organization principles, file formats, configuration, and best practices for maintaining documentation.

↑ Back to Navigation

Documentation Types

The system supports several types of documentation:

1. General Application Documentation - Common features like login, profile customization, visible to all sites and users
2. Site-Specific Documentation - Documentation specific to particular sites (MCOOP, CSC), only visible to users of that site
3. Role-Specific Documentation - Targeted at specific user roles (admin, developer), only visible to users with appropriate role
4. Module Documentation - Documentation for specific system modules with visibility dependent on module access permissions
5. Controller Documentation - System controller documentation primarily for developers and administrators
6. Changelog Documentation - System changes and updates to help track system evolution

↑ Back to Navigation

Visibility Rules

The documentation system applies the following visibility rules:

• CSC Site Administrators - Can see ALL documentation across all sites and roles (complete access)
• Site-Specific Visibility - Users can only see documentation for their current site; general documentation (site='all') visible to all sites
• Role-Based Visibility - Users can only see documentation appropriate for their role; higher roles can see documentation for lower roles
• Module-Specific Visibility - Module documentation visibility follows site and role rules with additional module-specific permissions

↑ Back to Navigation

Documentation Organization

Documentation is organized into the following categories:

• User Guides - Basic documentation for end users, getting started guides and FAQs
• Administrator Guides - Installation and configuration guides for system administrators
• Developer Documentation - API references and coding standards for developers
• Tutorials - Step-by-step guides for common tasks
• Controllers & Models Documentation - Technical documentation for developers and administrators
• Changelog - System changes visible to developers and administrators
• Proxmox Documentation - Virtualization environment documentation for administrators

↑ Back to Navigation

File Formats

The documentation system supports multiple file formats:

• Template Toolkit (.tt) - Primary format for documentation with proper META blocks, supports dynamic content, variables, and conditionals
• Markdown (.md) - Legacy format for quick drafts (not recommended for published documentation)
• Other Formats - JSON, HTML, CSS with appropriate content types

↑ Back to Navigation

Configuration

The documentation system uses a JSON configuration file for centralized management:

• documentation_config.json - Defines documentation categories, file paths, and metadata settings
• Configuration Structure - Categories section for all documentation types, default paths for documentation keys
• Updates - When adding new documentation, update configuration file and verify paths point to existing files

↑ Back to Navigation

Best Practices

When creating documentation, follow these best practices:

1. Proper Placement - Place documentation in appropriate directory based on type
2. Clear Metadata - Include title, author, date, status, and version in META block
3. Structured Content - Use proper headings, table of contents, and code blocks
4. Comprehensive Coverage - Cover all aspects, include examples and address common questions
5. Regular Updates - Keep documentation current with system changes and note update dates
6. Configuration Management - Update documentation_config.json when adding or moving documentation

↑ Back to Navigation

Debugging

The documentation system includes debugging features to help troubleshoot issues:

• Debug Mode - Enable debug mode to see detailed information about documentation loading and categorization
• Logging - The system logs documentation scanning and categorization; check application logs for errors
• Configuration Validation - The system validates documentation_config.json file; errors are logged

↑ Back to Navigation

Future Enhancements

Planned enhancements for the documentation system include:

• Improved Search - Full-text search across all documentation with advanced filtering
• Version Control - Track documentation changes over time and view previous versions
• User Feedback - Allow users to rate documentation and collect improvement suggestions
• Interactive Examples - Add interactive code examples, demos, and video tutorials
• Documentation Analytics - Track documentation access patterns and identify coverage gaps
• Further Template Improvements - Additional modularization, dynamic loading, and mobile responsiveness

↑ Back to Navigation

This documentation is part of the Comserv system. For technical support or questions, contact the system administrator.

Last Updated: December 18, 2025 | Version: 2.01 | Status: Active