📚 Documentation Guidelines

Welcome to the Documentation Guidelines! This document serves as a comprehensive guide for structuring, writing, and maintaining consistent and high-quality documentation across our projects. It covers common sections, formatting best practices, and useful Docusaurus features.

📝 Core Documentation Sections (Template Examples)

Every module or major feature should ideally follow a similar structure to ensure consistency and ease of navigation. Below are examples of common sections you would include in a module's index.mdx or feature-specific .mdx files.

🧭 Module Overview (Example Content)

This content would typically be in a module's index.mdx.

Briefly describe what this module does, its main purpose, and key functionality.

Example: This module manages course enrollment, including registration, seat allocation, and waitlisting logic. It provides APIs and UI components for administrators and students to manage their course registrations effectively.

🧩 Table Usage (Example Content)

This content might be in a module's features.mdx or index.mdx.

Use tables to clearly present data, features, or any structured information.

Feature	Description	Status
Create	Create a new item/entity	✅ Done
Read	Fetch list and details	✅ Done
Update	Modify existing records	🛠️ In Progress
Delete	Remove data	⛔ Blocked
Filtering	Support filters (date, type, status)	✅ Done
Sorting	Sort by columns (name, date, priority)	✅ Done
Pagination	Backend-integrated pagination	✅ Done

🔌 API Contract (Example Content)

This content would typically be in a module's api-contract.mdx.

Document your API endpoints with clear methods, descriptions, authentication requirements, and status.

Endpoint	Method	Description	Auth Required	Status
`/api/items`	GET	Fetch list of items	✅ Yes	✅ Done
`/api/items/:id`	PUT	Update item by ID	✅ Yes	🛠️ In Progress
`/api/items`	POST	Create a new item	✅ Yes	✅ Done
`/api/items/:id`	DELETE	Delete an item by ID	✅ Yes	⛔ Blocked

🎨 Design & Development Resources

This section provides quick links to common development and design assets.

✅ Storybook Links

These links typically go into a components-links.mdx file for a module.

Button: Storybook
Modal: Storybook

🎨 Figma Links

These links typically go into a components-links.mdx file for a module.

UI Design - Course Module

📦 Assumptions & Dependencies

This content would typically be in a module's assumptions-dependencies.mdx.

Crucial context for understanding the module's behavior and environment.

Relies on auth-token from global context for authentication.
Assumes courseId is passed via query parameter for specific operations.
External service UserProfileService is required and assumed to be available.
Backend pagination limit is fixed at 25 items per page for all list endpoints.

🔗 Linked Resources

Keep track of related project management and external documentation.

JIRA Epic: PROJ-1234: Course Module Development
Figma File: Course Module Designs
Postman Collection: API Test Suite for Course Module

👥 Contributors

Acknowledge team members who have contributed to the module or documentation.

Role	Name
Frontend Dev	Rajesh Kumar
Backend Dev	Mehul Singh
Designer	Anjali Verma
Product Owner	Priya Sethi

📁 Project File Overview (For Modules)

This section outlines a recommended file structure for individual module documentation folders.

File Name	Purpose
`_category_.json`	(Optional) Used by Docusaurus to organize items in the sidebar. Helps set titles, positions, and icons.
`index.mdx`	Module Overview – high-level summary and general information. Ideal for new readers.
`features.mdx`	Feature List – detailed breakdown of all supported features (e.g., CRUD, filtering, sorting).
`api-contract.mdx`	API Reference – defines REST or GraphQL contracts with endpoints, methods, request/response structure.
`components-links.mdx`	Design Assets – quick links to relevant Storybook components and Figma designs for developers and designers.
`assumptions-dependencies.mdx`	Contextual Notes – outlines assumptions made, external systems, services or libraries this module depends on.

✨ Docusaurus Markdown Features

Docusaurus supports a wide array of Markdown features beyond the basics, including Admonitions and Code Highlighting, and custom components. For an extensive list, refer to the official Docusaurus Markdown Features documentation.

📊 Admonitions (Cheatsheet)

Use these to highlight important notes, tips, warnings, or danger alerts.

Some content with Markdown syntax. Check this api.

🖥️ Code Highlighting

Code blocks are automatically highlighted based on the language. You can also add titles and highlight specific lines.

function HelloCodeTitle(props) {
  return <h1>Hello, {props.name}</h1>;
}
// This line is not highlighted
const name = "Docusaurus";