Files
ouranos/docs/documentation_style_guide.html

506 lines
26 KiB
HTML

<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Documentation Style Guide</title>
<!-- Bootstrap CSS -->
<link href="https://cdn.jsdelivr.net/npm/bootstrap@5.3.0/dist/css/bootstrap.min.css" rel="stylesheet">
<!-- Bootstrap Icons -->
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/bootstrap-icons@1.11.0/font/bootstrap-icons.css">
<style>
/* Smooth scrolling */
html {
scroll-behavior: smooth;
}
/* Icon styling */
.section-icon {
margin-right: 0.5rem;
color: var(--bs-primary);
}
.alert-icon {
margin-right: 0.5rem;
font-size: 1.2rem;
vertical-align: middle;
}
/* Scroll to top button */
#scrollTopBtn {
position: fixed;
bottom: 20px;
right: 20px;
z-index: 1000;
display: none;
border-radius: 50%;
width: 50px;
height: 50px;
box-shadow: 0 2px 10px rgba(0,0,0,0.3);
}
/* Icon legend */
.icon-legend {
display: inline-flex;
align-items: center;
margin-right: 1.5rem;
margin-bottom: 0.5rem;
}
.icon-legend i {
margin-right: 0.5rem;
font-size: 1.2rem;
}
</style>
</head>
<body>
<div class="container-fluid">
<nav class="navbar navbar-dark bg-dark rounded mb-4">
<div class="container-fluid">
<a class="navbar-brand" href="ouranos.html">
<i class="bi bi-arrow-left"></i> Back to Main Documentation
</a>
<div class="navbar-nav d-flex flex-row">
<a class="nav-link me-3" href="#philosophy"><i class="bi bi-book"></i> Philosophy</a>
<a class="nav-link me-3" href="#structure"><i class="bi bi-diagram-3"></i> Structure</a>
<a class="nav-link me-3" href="#visual-design"><i class="bi bi-palette"></i> Design</a>
<a class="nav-link me-3" href="#bootstrap-icons"><i class="bi bi-bootstrap"></i> Icons</a>
<a class="nav-link" href="#implementation"><i class="bi bi-gear"></i> Implementation</a>
</div>
</div>
</nav>
<nav aria-label="breadcrumb">
<ol class="breadcrumb">
<li class="breadcrumb-item"><a href="ouranos.html"><i class="bi bi-house-door"></i> Main Documentation</a></li>
<li class="breadcrumb-item active" aria-current="page">Style Guide</li>
</ol>
</nav>
<div class="row">
<div class="col-12">
<h1 class="display-4 mb-4">
<i class="bi bi-journal-code section-icon"></i>Documentation Style Guide
<span class="badge bg-success"><i class="bi bi-check-circle-fill"></i> Complete</span>
</h1>
<p class="lead">This guide explains the approach and principles used to create comprehensive HTML documentation for infrastructure and software projects.</p>
</div>
</div>
<!-- Icon Legend -->
<div class="alert alert-light border">
<h5><i class="bi bi-info-circle"></i> Icon Legend</h5>
<div class="d-flex flex-wrap">
<span class="icon-legend"><i class="bi bi-exclamation-triangle-fill text-danger"></i>Critical/Danger</span>
<span class="icon-legend"><i class="bi bi-exclamation-circle-fill text-warning"></i>Warning/Important</span>
<span class="icon-legend"><i class="bi bi-check-circle-fill text-success"></i>Success/Complete</span>
<span class="icon-legend"><i class="bi bi-info-circle-fill text-info"></i>Information</span>
<span class="icon-legend"><i class="bi bi-lightning-fill text-primary"></i>Active/Key</span>
<span class="icon-legend"><i class="bi bi-link-45deg text-secondary"></i>Integration</span>
</div>
</div>
<section id="philosophy" class="mb-5">
<h2 class="h2 mb-4"><i class="bi bi-book section-icon"></i>Philosophy</h2>
<div class="row g-4">
<div class="col-lg-4">
<div class="card h-100">
<div class="card-body">
<h3 class="card-title text-primary">
<i class="bi bi-diagram-3"></i> Documentation as Architecture
</h3>
<p>Documentation should mirror and reinforce the software architecture. Each component gets its own focused document that clearly explains its purpose, boundaries, and relationships.</p>
</div>
</div>
</div>
<div class="col-lg-4">
<div class="card h-100">
<div class="card-body">
<h3 class="card-title text-primary">
<i class="bi bi-people"></i> User-Centric Design
</h3>
<p>Documentation serves multiple audiences:</p>
<ul>
<li><i class="bi bi-code-slash"></i> <strong>Developers</strong> need technical details and implementation guidance</li>
<li><i class="bi bi-briefcase"></i> <strong>Stakeholders</strong> need high-level overviews and business context</li>
<li><i class="bi bi-award"></i> <strong>Red Panda</strong> needs approval checkpoints and critical decisions highlighted</li>
</ul>
</div>
</div>
</div>
<div class="col-lg-4">
<div class="card h-100">
<div class="card-body">
<h3 class="card-title text-primary">
<i class="bi bi-arrow-repeat"></i> Living Documentation
</h3>
<p>Documentation evolves with the codebase and captures both current state and architectural decisions.</p>
</div>
</div>
</div>
</div>
</section>
<section id="structure" class="mb-5">
<h2 class="h2 mb-4"><i class="bi bi-diagram-3 section-icon"></i>Structure Principles</h2>
<div class="alert alert-info border-start border-4 border-info">
<h3><i class="bi bi-info-circle-fill alert-icon"></i>1. Hierarchical Information Architecture</h3>
<pre class="mb-0">Main Documentation (project.html)
├── Component Docs (component1.html, component2.html, etc.)
├── Standards References (docs/standards/)
└── Supporting Materials (README.md, style guides)</pre>
</div>
<div class="alert alert-warning border-start border-4 border-warning">
<h3><i class="bi bi-exclamation-circle-fill alert-icon"></i>2. Consistent Navigation</h3>
<p>Every document includes:</p>
<ul class="mb-0">
<li><i class="bi bi-compass"></i> <strong>Navigation bar</strong> with key sections</li>
<li><i class="bi bi-link-45deg"></i> <strong>Cross-references</strong> to related components</li>
<li><i class="bi bi-arrow-return-left"></i> <strong>Return links</strong> to main documentation</li>
</ul>
</div>
<div class="alert alert-info border-start border-4 border-info">
<h3><i class="bi bi-info-circle-fill alert-icon"></i>3. Progressive Disclosure</h3>
<p>Information flows from general to specific:</p>
<p class="mb-0"><strong><i class="bi bi-arrow-right-short"></i> Overview → Architecture → Implementation → Details</strong></p>
</div>
</section>
<section id="visual-design" class="mb-5">
<h2 class="h2 mb-4"><i class="bi bi-palette section-icon"></i>Visual Design Principles</h2>
<div class="alert alert-info border-start border-4 border-info">
<h3><i class="bi bi-info-circle-fill alert-icon"></i>1. Clean Typography</h3>
<ul class="mb-0">
<li><i class="bi bi-fonts"></i> System fonts for readability</li>
<li><i class="bi bi-text-paragraph"></i> Generous line spacing (1.6)</li>
<li><i class="bi bi-list-nested"></i> Clear hierarchy with consistent heading sizes</li>
</ul>
</div>
<div class="alert alert-danger border-start border-4 border-danger">
<h3><i class="bi bi-exclamation-triangle-fill alert-icon"></i>2. Color-Coded Information Types</h3>
<p><strong><i class="bi bi-bootstrap"></i> Bootstrap Alert Classes (Preferred):</strong></p>
<ul class="mb-3">
<li><i class="bi bi-exclamation-triangle-fill text-danger"></i> <code>alert alert-danger</code> - Critical decisions requiring immediate attention</li>
<li><i class="bi bi-exclamation-circle-fill text-warning"></i> <code>alert alert-warning</code> - Important context and warnings</li>
<li><i class="bi bi-check-circle-fill text-success"></i> <code>alert alert-success</code> - Completed features and positive outcomes</li>
<li><i class="bi bi-info-circle-fill text-info"></i> <code>alert alert-info</code> - Technical architecture information</li>
<li><i class="bi bi-lightning-fill text-primary"></i> <code>alert alert-primary</code> - Key workflows and processes</li>
<li><i class="bi bi-link-45deg text-secondary"></i> <code>alert alert-secondary</code> - Cross-component integration details</li>
</ul>
<p><strong>Legacy Custom Classes (Backward Compatible):</strong></p>
<ul class="mb-0">
<li><i class="bi bi-circle-fill text-info"></i> <strong>.tech-stack</strong> - Technical architecture information</li>
<li><i class="bi bi-circle-fill text-warning"></i> <strong>.critical</strong> - Important decisions requiring attention</li>
<li><i class="bi bi-circle-fill text-primary"></i> <strong>.workflow</strong> - Process and workflow information</li>
<li><i class="bi bi-circle-fill text-secondary"></i> <strong>.integration</strong> - Cross-component integration details</li>
</ul>
</div>
<div class="alert alert-info border-start border-4 border-info">
<h3><i class="bi bi-info-circle-fill alert-icon"></i>3. Responsive Layout</h3>
<ul class="mb-0">
<li><i class="bi bi-phone"></i> Bootstrap grid system for all screen sizes</li>
<li><i class="bi bi-grid-3x3"></i> Consistent spacing with utility classes</li>
<li><i class="bi bi-card-list"></i> Card-based information grouping</li>
</ul>
</div>
</section>
<section id="bootstrap-icons" class="mb-5">
<h2 class="h2 mb-4"><i class="bi bi-bootstrap section-icon"></i>Bootstrap Icons Integration</h2>
<div class="alert alert-success border-start border-4 border-success">
<h3><i class="bi bi-check-circle-fill alert-icon"></i>Setup</h3>
<p>Add Bootstrap Icons CDN to your HTML documents:</p>
<div class="bg-light p-3 rounded my-2">
<code>&lt;link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/bootstrap-icons@1.11.0/font/bootstrap-icons.css"&gt;</code>
</div>
<p class="mt-3"><strong>Benefits:</strong></p>
<ul class="mb-0">
<li><i class="bi bi-lightning-charge"></i> Minimal overhead (~75KB)</li>
<li><i class="bi bi-palette"></i> 2000+ icons matching Bootstrap design</li>
<li><i class="bi bi-cloud-download"></i> CDN caching for fast loading</li>
</ul>
</div>
<div class="alert alert-info border-start border-4 border-info">
<h3><i class="bi bi-info-circle-fill alert-icon"></i>Common Icon Patterns</h3>
<div class="row g-3">
<div class="col-md-6">
<h5><i class="bi bi-check-square"></i> Status & Progress</h5>
<ul>
<li><i class="bi bi-check-square"></i> <code>bi-check-square</code> - Completed</li>
<li><i class="bi bi-square"></i> <code>bi-square</code> - Pending</li>
<li><i class="bi bi-hourglass-split"></i> <code>bi-hourglass-split</code> - In Progress</li>
<li><i class="bi bi-x-circle"></i> <code>bi-x-circle</code> - Failed/Error</li>
</ul>
</div>
<div class="col-md-6">
<h5><i class="bi bi-compass"></i> Navigation</h5>
<ul>
<li><i class="bi bi-house-door"></i> <code>bi-house-door</code> - Home</li>
<li><i class="bi bi-arrow-left"></i> <code>bi-arrow-left</code> - Back</li>
<li><i class="bi bi-box-arrow-up-right"></i> <code>bi-box-arrow-up-right</code> - External</li>
<li><i class="bi bi-link-45deg"></i> <code>bi-link-45deg</code> - Link</li>
</ul>
</div>
<div class="col-md-6">
<h5><i class="bi bi-exclamation-triangle"></i> Alerts</h5>
<ul>
<li><i class="bi bi-exclamation-triangle-fill text-danger"></i> <code>bi-exclamation-triangle-fill</code> - Danger</li>
<li><i class="bi bi-exclamation-circle-fill text-warning"></i> <code>bi-exclamation-circle-fill</code> - Warning</li>
<li><i class="bi bi-info-circle-fill text-info"></i> <code>bi-info-circle-fill</code> - Info</li>
<li><i class="bi bi-check-circle-fill text-success"></i> <code>bi-check-circle-fill</code> - Success</li>
</ul>
</div>
<div class="col-md-6">
<h5><i class="bi bi-code-slash"></i> Technical</h5>
<ul>
<li><i class="bi bi-code-slash"></i> <code>bi-code-slash</code> - Code</li>
<li><i class="bi bi-database"></i> <code>bi-database</code> - Database</li>
<li><i class="bi bi-cpu"></i> <code>bi-cpu</code> - System</li>
<li><i class="bi bi-plug"></i> <code>bi-plug</code> - API/Integration</li>
</ul>
</div>
</div>
</div>
<div class="alert alert-primary border-start border-4 border-primary">
<h3><i class="bi bi-lightning-fill alert-icon"></i>Usage Examples</h3>
<h5 class="mt-3">Section Headers with Icons</h5>
<div class="bg-light p-3 rounded my-2">
<code>&lt;h2&gt;&lt;i class="bi bi-book section-icon"&gt;&lt;/i&gt;Section Title&lt;/h2&gt;</code>
</div>
<h5 class="mt-3">Alert Boxes with Icons</h5>
<div class="bg-light p-3 rounded my-2">
<code>&lt;div class="alert alert-info border-start border-4 border-info"&gt;<br>
&nbsp;&nbsp;&lt;h3&gt;&lt;i class="bi bi-info-circle-fill alert-icon"&gt;&lt;/i&gt;Information&lt;/h3&gt;<br>
&lt;/div&gt;</code>
</div>
<h5 class="mt-3">Badges with Icons</h5>
<div class="bg-light p-3 rounded my-2">
<code>&lt;span class="badge bg-success"&gt;&lt;i class="bi bi-check-circle-fill"&gt;&lt;/i&gt; Complete&lt;/span&gt;</code>
</div>
<h5 class="mt-3">List Items with Icons</h5>
<div class="bg-light p-3 rounded my-2">
<code>&lt;li&gt;&lt;i class="bi bi-check-circle"&gt;&lt;/i&gt; Completed task&lt;/li&gt;<br>
&lt;li&gt;&lt;i class="bi bi-arrow-right-short"&gt;&lt;/i&gt; Action item&lt;/li&gt;</code>
</div>
</div>
<div class="alert alert-warning border-start border-4 border-warning">
<h3><i class="bi bi-exclamation-circle-fill alert-icon"></i>Best Practices</h3>
<ul class="mb-0">
<li><i class="bi bi-check-circle"></i> Use semantic icons that match content meaning</li>
<li><i class="bi bi-palette"></i> Maintain consistent icon usage across documents</li>
<li><i class="bi bi-eye"></i> Don't overuse icons - they should enhance, not clutter</li>
<li><i class="bi bi-phone"></i> Ensure icons are visible and meaningful at all screen sizes</li>
<li><i class="bi bi-universal-access"></i> Icons should supplement text, not replace it (accessibility)</li>
</ul>
</div>
</section>
<section id="implementation" class="mb-5">
<h2 class="h2 mb-4"><i class="bi bi-gear section-icon"></i>Implementation Guidelines</h2>
<div class="alert alert-success border-start border-4 border-success">
<h3><i class="bi bi-check-circle-fill alert-icon"></i>HTML Document Template</h3>
<pre class="mb-0">&lt;!DOCTYPE html&gt;
&lt;html lang="en"&gt;
&lt;head&gt;
&lt;meta charset="UTF-8"&gt;
&lt;meta name="viewport" content="width=device-width, initial-scale=1.0"&gt;
&lt;title&gt;Document Title&lt;/title&gt;
&lt;!-- Bootstrap CSS --&gt;
&lt;link href="https://cdn.jsdelivr.net/npm/bootstrap@5.3.0/dist/css/bootstrap.min.css" rel="stylesheet"&gt;
&lt;!-- Bootstrap Icons --&gt;
&lt;link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/bootstrap-icons@1.11.0/font/bootstrap-icons.css"&gt;
&lt;/head&gt;
&lt;body&gt;
&lt;div class="container-fluid"&gt;
&lt;!-- Navigation --&gt;
&lt;nav class="navbar navbar-dark bg-dark rounded mb-4"&gt;
&lt;a class="navbar-brand" href="main.html"&gt;
&lt;i class="bi bi-arrow-left"&gt;&lt;/i&gt; Back
&lt;/a&gt;
&lt;/nav&gt;
&lt;!-- Breadcrumb --&gt;
&lt;nav aria-label="breadcrumb"&gt;
&lt;ol class="breadcrumb"&gt;
&lt;li class="breadcrumb-item"&gt;&lt;a href="main.html"&gt;&lt;i class="bi bi-house-door"&gt;&lt;/i&gt; Main&lt;/a&gt;&lt;/li&gt;
&lt;li class="breadcrumb-item active"&gt;Current Page&lt;/li&gt;
&lt;/ol&gt;
&lt;/nav&gt;
&lt;!-- Content --&gt;
&lt;h1&gt;&lt;i class="bi bi-journal-code"&gt;&lt;/i&gt; Page Title&lt;/h1&gt;
&lt;!-- Sections --&gt;
&lt;/div&gt;
&lt;!-- Bootstrap JS --&gt;
&lt;script src="https://cdn.jsdelivr.net/npm/bootstrap@5.3.0/dist/js/bootstrap.bundle.min.js"&gt;&lt;/script&gt;
&lt;!-- Dark mode support --&gt;
&lt;script&gt;
if (window.matchMedia('(prefers-color-scheme: dark)').matches) {
document.documentElement.setAttribute('data-bs-theme', 'dark');
}
&lt;/script&gt;
&lt;/body&gt;
&lt;/html&gt;</pre>
</div>
<div class="alert alert-info border-start border-4 border-info">
<h3><i class="bi bi-info-circle-fill alert-icon"></i>Dark Mode Support</h3>
<p>Bootstrap 5.3+ includes built-in dark mode support. Add this script to automatically detect system preferences:</p>
<div class="bg-light p-3 rounded my-2">
<code>&lt;script&gt;<br>
&nbsp;&nbsp;if (window.matchMedia('(prefers-color-scheme: dark)').matches) {<br>
&nbsp;&nbsp;&nbsp;&nbsp;document.documentElement.setAttribute('data-bs-theme', 'dark');<br>
&nbsp;&nbsp;}<br>
&lt;/script&gt;</code>
</div>
</div>
<div class="alert alert-primary border-start border-4 border-primary">
<h3><i class="bi bi-lightning-fill alert-icon"></i>Scroll to Top Button</h3>
<p>Add a floating button for easy navigation in long documents:</p>
<div class="bg-light p-3 rounded my-2">
<code>&lt;button id="scrollTopBtn" class="btn btn-primary"&gt;<br>
&nbsp;&nbsp;&lt;i class="bi bi-arrow-up-circle"&gt;&lt;/i&gt;<br>
&lt;/button&gt;<br><br>
&lt;script&gt;<br>
&nbsp;&nbsp;window.onscroll = function() {<br>
&nbsp;&nbsp;&nbsp;&nbsp;if (document.documentElement.scrollTop &gt; 300) {<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;document.getElementById('scrollTopBtn').style.display = 'block';<br>
&nbsp;&nbsp;&nbsp;&nbsp;} else {<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;document.getElementById('scrollTopBtn').style.display = 'none';<br>
&nbsp;&nbsp;&nbsp;&nbsp;}<br>
&nbsp;&nbsp;};<br>
&nbsp;&nbsp;document.getElementById('scrollTopBtn').onclick = function() {<br>
&nbsp;&nbsp;&nbsp;&nbsp;window.scrollTo({top: 0, behavior: 'smooth'});<br>
&nbsp;&nbsp;};<br>
&lt;/script&gt;</code>
</div>
</div>
</section>
<section id="quality-standards" class="mb-5">
<h2 class="h2 mb-4"><i class="bi bi-award section-icon"></i>Quality Standards</h2>
<div class="progress mb-4">
<div class="progress-bar bg-success" style="width: 100%">
<i class="bi bi-check-circle-fill"></i> Style Guide Implementation: 100% Complete
</div>
</div>
<div class="row g-4">
<div class="col-lg-4">
<div class="card h-100">
<div class="card-body">
<h3 class="card-title text-primary">
<i class="bi bi-check-circle"></i> Technical Accuracy
</h3>
<ul class="mb-0">
<li>All code examples must work</li>
<li>All URLs must be valid</li>
<li>All relationships must be correct</li>
</ul>
</div>
</div>
</div>
<div class="col-lg-4">
<div class="card h-100">
<div class="card-body">
<h3 class="card-title text-primary">
<i class="bi bi-eye"></i> Clarity and Completeness
</h3>
<ul class="mb-0">
<li>Each section serves a specific purpose</li>
<li>Information is neither duplicated nor missing</li>
<li>Cross-references are accurate</li>
</ul>
</div>
</div>
</div>
<div class="col-lg-4">
<div class="card h-100">
<div class="card-body">
<h3 class="card-title text-primary">
<i class="bi bi-stars"></i> Professional Presentation
</h3>
<ul class="mb-0">
<li>Consistent formatting throughout</li>
<li>Clean visual hierarchy</li>
<li>Responsive design for all devices</li>
</ul>
</div>
</div>
</div>
</div>
</section>
<div class="alert alert-secondary border-start border-4 border-secondary">
<p class="mb-0">
<i class="bi bi-award"></i> <strong>This style guide ensures consistent, professional, and maintainable documentation that serves both technical and business needs while supporting the long-term success of your projects.</strong>
</p>
</div>
<!-- Scroll to top button -->
<button id="scrollTopBtn" class="btn btn-primary" title="Scroll to top">
<i class="bi bi-arrow-up-circle"></i>
</button>
</div>
<!-- Bootstrap JS -->
<script src="https://cdn.jsdelivr.net/npm/bootstrap@5.3.0/dist/js/bootstrap.bundle.min.js"></script>
<!-- Dark mode support -->
<script>
// Detect system preference and apply dark mode
if (window.matchMedia('(prefers-color-scheme: dark)').matches) {
document.documentElement.setAttribute('data-bs-theme', 'dark');
}
// Listen for changes in system preference
window.matchMedia('(prefers-color-scheme: dark)').addEventListener('change', function(e) {
if (e.matches) {
document.documentElement.setAttribute('data-bs-theme', 'dark');
} else {
document.documentElement.setAttribute('data-bs-theme', 'light');
}
});
// Scroll to top button functionality
window.onscroll = function() {
const scrollBtn = document.getElementById('scrollTopBtn');
if (document.body.scrollTop > 300 || document.documentElement.scrollTop > 300) {
scrollBtn.style.display = 'block';
} else {
scrollBtn.style.display = 'none';
}
};
document.getElementById('scrollTopBtn').onclick = function() {
window.scrollTo({top: 0, behavior: 'smooth'});
};
</script>
</body>
</html>