Documentation Template

Overview

This template provides a standardized format for creating new documentation in the Comserv system using the Template Toolkit (.tt) format. Following this template ensures that all documentation is consistent and properly formatted for browser display.

Template Toolkit Header Section

Every .tt documentation file should begin with a proper Template Toolkit header section. This section contains metadata and debug information:

0

Required Header Fields

• META title: The title of the document (use single quotes, no variable concatenation)
• PageVersion: File path, version number, date, and author information
• Debug block: Standard debugging information for Template Toolkit processing

Document Structure

HTML Formatting

Use HTML tags instead of Markdown syntax in .tt files:

• Headings: Use <h1>, <h2>, <h3> tags
• Paragraphs: Use <p> tags
• Lists: Use <ul>, <ol>, <li> tags
• Code: Use <pre> tags for code blocks
• Emphasis: Use <strong> and <em> tags

Main Heading

The document should start with a level 1 heading (<h1>) that matches the title in the META section.

Overview Section

Begin with an overview section that briefly explains the purpose and scope of the document.

Main Sections

Organize the document into logical sections using level 2 headings (<h2>).

Subsections

Use level 3 headings (<h3>) for subsections within main sections.

Formatting Guidelines

Code Blocks

Use <pre> tags for code examples with proper HTML escaping:

sub example_function {
    my ($self, $param) = @_;
    return $param;
}

Lists

Use HTML list tags for unordered items:

• Item 1
• Item 2
• Item 3

Use numbered lists for sequential steps:

1. First step
2. Second step
3. Third step

Tables

Use HTML table tags for tabular data:

Important Notes and Warnings

Use appropriate HTML formatting for notes and warnings:

Note: This is an important note that users should be aware of.

Warning: This is a warning about potential issues.

Template Examples

Example User Guide Template

0


<h1>User Profile Management</h1>

<h2>Overview</h2>

<p>This guide explains how to manage your user profile in the Comserv system, including updating personal information, changing your password, and configuring notification preferences.</p>

<h2>Accessing Your Profile</h2>

<ol>
<li>Log in to the Comserv system</li>
<li>Click on your username in the top-right corner</li>
<li>Select "Profile" from the dropdown menu</li>
</ol>

Example Admin Guide Template

0


<h1>User Role Management</h1>

<h2>Overview</h2>

<p>This guide explains how administrators can manage user roles in the Comserv system, including assigning roles, creating custom roles, and configuring role permissions.</p>

<h2>Accessing Role Management</h2>

<ol>
<li>Log in to the Comserv system as an administrator</li>
<li>Navigate to Admin > User Management > Roles</li>
</ol>

File Placement Guidelines

Place documentation files in the appropriate subdirectory:

• /general/ - General documentation and templates
• /controllers/ - Controller-specific documentation
• /models/ - Model-specific documentation
• /deployment/ - Deployment and server setup guides
• /system/ - System-level documentation
• /themes/ - Theme system documentation
• /tutorials/ - User and developer tutorials
• /changelog/ - Change log entries

Related Documentation

• AI Documentation Guidelines
• Template Toolkit Reference
• Documentation System Overview

Conclusion

Following this template ensures that all documentation is consistent, properly formatted for Template Toolkit processing, and displays correctly in the browser. The .tt format allows for dynamic content and proper integration with the Comserv system.