Documentation

— by Youcef MADADI, FREELANCER & PROJECT MANAGER

Index

JSDocs

Compodoc

Storybook

Generating a library

Introduction to Documentation

The Foundation of Effective Communication in Software Development

What is Documentation?

Documentation is the organized recording of information for communication, learning, or maintaining software systems.

Purpose in Software Development:

To communicate how a system works.
To guide users and developers.
To serve as a reference for future maintenance.

Types of Documentation

Code Documentation:

Inline comments.
API documentation.

Process Documentation:

Requirements specifications.
Design documents.

User Documentation

Manuals.
Help guides.

Team Documentation:

Project wikis.
Meeting notes.

Why is Documentation Important?

Improves Collaboration:

Helps team members understand the system.

Enhances Onboarding:

Speeds up training for new developers.

Facilitates Maintenance:

Provides context for debugging and updates.

Ensures Knowledge Retention:

Reduces dependency on individual contributors.

Characteristics of Good Documentation

Clear:

Use simple language and avoid jargon.

Consistent:

Follow a uniform format and style.

Comprehensive:

Cover all necessary details without overwhelming.

Accessible:

Easy to find and understand for the intended audience.

Up-to-Date:

Regularly update to reflect changes in the system.

Common Tools for Documentation

For Code Documentation:

JSDoc, Doxygen, typescripts comments.

For Team Collaboration:

Confluence, Notion, Google Docs.

For User Documentation:

Markdown editors, HelpNDoc.

For Automated Documentation:

Swagger for APIs, Compodoc for Angular.

Challenges in Documentation

Time-Consuming:

Balancing documentation and coding time.

Engagement:

Ensuring all team members contribute.

Maintaining Accuracy:

Keeping documentation up-to-date.

Over-documenting:

Avoiding excessive and redundant information.

Best Practices for Documentation

Integrate Documentation into Development:

Write documentation as part of the coding process.

Make It Collaborative:

Encourage team input.

Use Version Control:

Track changes to documentation alongside code.

Automate Where Possible:

Use tools to generate repetitive or structured documentation.

Enhance Clarity and Collaboration Through Structured Comments

Documenting Angular Projects with JSDoc

What is JSDoc?

JSDoc is a popular syntax for adding structured comments to JavaScript or TypeScript code.

Purpose

Enhances code readability.
Provides detailed documentation for tools like Compodoc.

Benefits

Easier onboarding for new team members.
Automated generation of API documentation.

Basic JSDoc Syntax

Single-line Comments:

/** A single-line comment */

Multi-line Comments:

/**
 * A detailed multi-line comment.
 * Useful for describing complex methods or components.
 */

Annotations

Use @param, @return, @type, etc., for structured comments.

Basic JSDoc Syntax

Documenting Classes:

/**
 * Represents a user in the application.
 * Handles user-related functionality like authentication.
 */
export class User {
  // Class implementation
}

Documenting Properties:

/**
 * A list of the user's roles.
 * @type {string[]}
 */
roles: string[];

Basic JSDoc Syntax

Documenting Methods:

/**
 * Logs the user into the system.
 * @param {string} username - The user's username.
 * @param {string} password - The user's password.
 * @returns {boolean} - Whether the login was successful.
 */
login(username: string, password: string): boolean {
  return true;
}

Documenting Interfaces

/**
 * Represents a user object structure.
 */
export interface User {
  /** The unique identifier for the user. */
  id: string;

  /** The full name of the user. */
  name: string;

  /** The user's email address. */
  email: string;
}

Simplify Your Angular Project Documentation

Automating Documentation with Compodoc

What is Compodoc?

Compodoc is a powerful documentation generator for Angular applications.

Key Features:

Generates a comprehensive static site.
Provides a visual representation of your app’s structure.
Includes coverage for components, modules, services, and more.

Why Use Compodoc?

Saves time by automating documentation.
Improves team collaboration with up-to-date documentation.

Installing Compodoc

Install Compodoc using npm:

npm install -g @compodoc/compodoc

Verify installation:

compodoc --v

Installing Compodoc

Run Compodoc in your project:

compodoc -p tsconfig.json

Open the documentation:

compodoc -s

Key Features of the Generated Documentation

Interactive Menu: Navigate through modules, components, and services.
Visual Dependency Graphs: View relationships between modules and components.
Code Coverage: Assess how well your project is documented.
Markdown Support: Add README files and custom content.

Customizing Documentation

Adding a Logo:

{
  "logo": "./path-to-logo.png"
}

Create a compodoc.json configuration file.
Add the logo path:

Changing Theme:

{
  "theme": "readthedocs"
}

Choose themes like readthedocs, material, etc.
Update in compodoc.json:

Best Practices for Using Compodoc

Document As You Code:
- Use comments consistently for methods, classes, and interfaces.
Integrate with CI/CD:
- Automate documentation updates in your deployment pipeline.
Combine with Storybook:
- Use Storybook for visual component documentation alongside Compodoc.

Streamlining UI Development and Testing

Introduction to Storybook in Angular

Compodoc is a powerful documentation generator for Angular applications.

Advantages:

Focus on one component at a time without worrying about app logic.
Shareable UI documentation.
Easy collaboration with designers and developers.
Simplifies testing UI edge cases.

Why Use Storybook?

How Does Storybook Work?

Compodoc is a powerful documentation generator for Angular applications.

Process Overview:

Install Storybook into your project.
Write "stories" for your components.
Run Storybook locally or deploy it.
Core Idea: A "story" is a visual state of a component.

Setting Up Storybook in Angular

Install Storybook

npx storybook@latest init

Start Storybook:

npm run storybook

Basic Story Example:

import { Meta, Story } from '@storybook/angular';
import { ButtonComponent } from './button.component';

export default {
  title: 'Components/Button',
  component: ButtonComponent,
} as Meta;

const Template: Story = (args) => ({
  props: args,
});

export const Primary = Template.bind({});
Primary.args = {
  label: 'Primary Button',
  color: 'primary',
};

export const Secondary = Template.bind({});
Secondary.args = {
  label: 'Secondary Button',
  color: 'secondary',
};

Writing Your First Story

Examples to Apply

Button Component:
- Write stories for different button states (primary, secondary, disabled).
Card Component:
- Write stories for cards with varying content.

Creating and Publishing Angular Libraries

Reusable, Scalable, and Shareable Code

Definition:

A library in Angular is a set of reusable code components, services, or utilities.
Designed for sharing functionality across applications or teams.

What is an Angular Library?

Key Characteristics:

Packaged as an npm module or private git.
Integrates seamlessly into Angular projects.

Advantages:

Reusability: Share components/services across multiple apps.
Maintainability: Centralized updates for consistent functionality.
Customization: Tailored components for specific use cases.

Why Build Angular Libraries?

Setting Up an Angular Library

Generate a Library

ng generate library my-library

Build the Library

ng build my-library

Adding Components to the Library

Generate a Component

ng generate component button --project=my-library

Edit the Component

@Component({
  selector: 'lib-button',
  template: `<button [ngClass]="type">{{ label }}</button>`,
  styles: [/* Add styles */]
})
export class ButtonComponent {
  @Input() label: string = 'Default';
  @Input() type: string = 'primary';
}

Testing the Library Locally

Build the Library

ng build my-library

Add it to an Angular app In package.json

"dependencies": {
  "my-library": "file:../dist/my-library"
}

Build the Library

ng build my-library

Initialize a Git repository in the library folder:

cd projects/my-library
git init

Steps to Host an Angular Library in Git

Commit and push

git add .
git commit -m "Initial commit"
git branch -M main
git push -u origin main

Add remote origin

git remote add origin <your-repo-url>

Add the Git-based dependency in package.json:

"dependencies": {
  "my-library": "git+https://<your-repo-url>#<branch-or-tag>"
}

Install the library

npm install

Create a new version tag:

git tag v1.0.0
git push origin v1.0.0

Update package.json to specify the version

"my-library": "git+https://<your-repo-url>#v1.0.0"

Manage Versioning

Documentation

— by Youcef MADADI, FREELANCER & PROJECT MANAGER

Index

Introduction to Documentation

What is Documentation?

Types of Documentation

Why is Documentation Important?

Characteristics of Good Documentation

Common Tools for Documentation

Challenges in Documentation

Best Practices for Documentation

Documenting Angular Projects with JSDoc

What is JSDoc?

Basic JSDoc Syntax

Basic JSDoc Syntax

Basic JSDoc Syntax

Automating Documentation with Compodoc

What is Compodoc?

Installing Compodoc

Installing Compodoc

Key Features of the Generated Documentation

Customizing Documentation

Best Practices for Using Compodoc

Introduction to Storybook in Angular

Why Use Storybook?

How Does Storybook Work?

Setting Up Storybook in Angular

Writing Your First Story

Examples to Apply

Creating and Publishing Angular Libraries

What is an Angular Library?

Why Build Angular Libraries?

Setting Up an Angular Library

Adding Components to the Library

Testing the Library Locally

Steps to Host an Angular Library in Git

Manage Versioning

Angular training - Documentation

Angular training - Documentation

Youcef Madadi

Documentation

— by Youcef MADADI, FREELANCER & PROJECT MANAGER

Index

Introduction to Documentation

What is Documentation?

Types of Documentation

Why is Documentation Important?

Characteristics of Good Documentation

Common Tools for Documentation

Challenges in Documentation

Best Practices for Documentation

Documenting Angular Projects with JSDoc

What is JSDoc?

Basic JSDoc Syntax

Basic JSDoc Syntax

Basic JSDoc Syntax

Automating Documentation with Compodoc

What is Compodoc?

Installing Compodoc

Installing Compodoc

Key Features of the Generated Documentation

Customizing Documentation

Best Practices for Using Compodoc

Introduction to Storybook in Angular

Why Use Storybook?

How Does Storybook Work?

Setting Up Storybook in Angular

Writing Your First Story

Examples to Apply

Creating and Publishing Angular Libraries

What is an Angular Library?

Why Build Angular Libraries?

Setting Up an Angular Library

Adding Components to the Library

Testing the Library Locally

Steps to Host an Angular Library in Git

Manage Versioning

Angular training - Documentation

More from Youcef Madadi