Building Your Learning Module...
Getting things ready for you!
Find videos you like?
Save to resource drawer for future reference!
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>HTML Documentation Best Practices</title>
</head>
<body>
<div class="container">
<h1>📝 HTML Documentation Examples</h1>
<!-- Section Comments -->
<div class="doc-section">
<h2>1. Section Comments</h2>
<p style="color: #6b7280; margin-bottom: 15px;">
Use comments to mark major sections of your HTML document.
</p>
<pre><span class="good-comment"><!-- ========================================
HEADER SECTION
Contains logo, navigation, and search
======================================== --></span>
<header class="site-header">
<!-- Logo -->
<img src="logo.png" alt="Company Logo">
<!-- Main Navigation -->
<nav aria-label="Main">
<ul>
<li><a href="/">Home</a></li>
<li><a href="/about">About</a></li>
</ul>
</nav>
</header>
<span class="good-comment"><!-- ========================================
MAIN CONTENT
======================================== --></span>
<main>
<!-- Content goes here -->
</main></pre>
</div>
<!-- Component Documentation -->
<div class="doc-section">
<h2>2. Component Documentation</h2>
<p style="color: #6b7280; margin-bottom: 15px;">
Document reusable components with their purpose and usage.
</p>
<pre><span class="good-comment"><!--
PRODUCT CARD COMPONENT
Purpose: Display product information in a card format
Required:
- .product-card: Main container
- .product-card__image: Product image
- .product-card__title: Product name
- .product-card__price: Price display
Optional:
- .product-card--featured: Featured product style
- .product-card__badge: Sale/New badge
Example:
<article class="product-card">
<img class="product-card__image" src="...">
<h3 class="product-card__title">Product Name</h3>
<span class="product-card__price">$99</span>
</article>
--></span>
<article class="product-card">
<img class="product-card__image" src="product.jpg" alt="Product">
<h3 class="product-card__title">Laptop</h3>
<span class="product-card__price">$999</span>
</article></pre>
</div>
<!-- Good vs Bad Comments -->
<div class="doc-section">
<h2>3. Good vs Bad Comments</h2>
<div class="example-grid">
<div class="example-card bad-example">
<h4>❌ Bad Comments</h4>
<pre style="font-size: 0.7rem;"><span class="comment"><!-- div --></span>
<div class="container">
<span class="comment"><!-- heading --></span>
<h1>Title</h1>
<span class="comment"><!-- This is a paragraph tag --></span>
<p>Text</p>
<span class="comment"><!-- end div --></span>
</div></pre>
<p style="color: #991b1b; font-size: 0.85rem; margin-top: 10px;">
Too obvious, no value added
</p>
</div>
<div class="example-card good-example">
<h4>✅ Good Comments</h4>
<pre style="font-size: 0.7rem;"><span class="good-comment"><!-- Hero Section --></span>
<div class="hero-container">
<span class="good-comment"><!-- Page Title - Updated via CMS --></span>
<h1>Welcome</h1>
<span class="good-comment"><!-- Introduction text --></span>
<p>Description text...</p>
</div>
<span class="good-comment"><!-- /Hero Section --></span></pre>
<p style="color: #065f46; font-size: 0.85rem; margin-top: 10px;">
Adds context and useful information
</p>
</div>
</div>
</div>
<!-- TODO Comments -->
<div class="doc-section">
<h2>4. TODO Comments</h2>
<p style="color: #6b7280; margin-bottom: 15px;">
Mark incomplete work or future improvements.
</p>
<pre><span class="good-comment"><!-- TODO: Add accessibility labels to form inputs --></span>
<form>
<input type="text" name="username">
</form>
<span class="good-comment"><!-- FIXME: Image alt text needs updating --></span>
<img src="photo.jpg" alt="Image">
<span class="good-comment"><!-- NOTE: This component is deprecated, use <new-component> instead --></span>
<div class="old-component"></div></pre>
</div>
<div style="background: #fef3c7; padding: 20px; border-radius: 12px; border-left: 4px solid #f59e0b; margin-top: 30px;">
<h3 style="color: #78350f; margin-bottom: 10px;">💡 Documentation Tips</h3>
<ul style="list-style: none; line-height: 2; color: #92400e;">
<li>✓ Comment WHY, not WHAT (code shows what)</li>
<li>✓ Document complex sections only</li>
<li>✓ Keep comments up-to-date</li>
<li>✓ Use TODO/FIXME/NOTE prefixes</li>
<li>✓ Remove commented-out code before commit</li>
</ul>
</div>
</div>
</body>
</html>Loading preview...
Mark major sections of your page
<!-- ===== HEADER SECTION ===== -->Explain why something is done a certain way
<!-- Using inline styles here due to email client compatibility -->Mark incomplete work or future improvements
<!-- TODO: Add error handling for empty form submission -->Document reusable components with usage examples
<!-- CARD COMPONENT: Requires .card, .card__title, .card__body -->Mark closing tags for long sections
</section> <!-- /Hero Section --><!-- TODO: Add form validation --><!-- FIXME: Broken link on mobile --><!-- HACK: IE11 compatibility fix --><!-- NOTE: Don't modify this without updating CSS --><!-- WARNING: Changes here affect entire site -->