Как ведется документация проекта?

Как ведется документация проекта?

Стратегия документирования

Документация — это не один файл README, это многоуровневая система. В моих проектах документация живет в нескольких местах и служит разным целям.

1. README.md — Входная точка

В корне проекта — краткое введение:

# PrepBro Frontend

Платформа подготовки к IT-собеседованиям.

## Quick Start

```bash
npm install
npm run dev

Tech Stack

• Next.js 16
• React 19
• Tailwind CSS v4
• TypeScript

Project Structure

frontend/
  src/

app/          # App Router pages
components/   # Reusable components
hooks/        # Custom React hooks
lib/          # Utilities and helpers
types/        # TypeScript types

Getting Help

See docs/ for detailed documentation.

### 2. Architecture Documentation

**docs/architecture/** — как устроено приложение:

```markdown
# Architecture

## Component Structure

### Presentation Layer
- `components/ui/` — базовые UI компоненты (Button, Card)
- `components/layout/` — Layout, Header, Footer
- `components/sections/` — секции лендинга

### Feature Layer
- `components/{feature}/` — специфичные компоненты
  - `components/questions/QuestionCard.tsx`
  - `components/questions/QuestionList.tsx`

### Application Layer
- `hooks/` — логика состояния и побочных эффектов
- `lib/api.ts` — запросы на сервер
- `contexts/` — глобальное состояние

## Data Flow

UI Component -> Hook (useQuery) -> API Client -> Backend

## Rules

- Components are pure, logic in hooks
- No data fetching in render
- All types defined (no `any`)

3. Features & Patterns

docs/guides/ — как работать с общими паттернами:

# Testing Guide

## Unit Tests

Все компоненты имеют `.test.tsx` файлы.

```typescript

describe('Button Component', () => {

  it('renders with children', () => {

const { getByText } = render(
  <Button>Click me</Button>
);
expect(getByText('Click me')).toBeInTheDocument();

  });
});

E2E Tests

Используем Playwright для критичных flows.

Coverage

Цель: >= 90% coverage. Проверяй:

npm run test:coverage

### 4. API Documentation

**docs/api/** — интеграция с бэкендом:

```markdown
# API Endpoints

## Authentication

### POST /api/v1/auth/login

Авторизация пользователя.

**Request:**
```json
{
  "email": "user@example.com",
  "password": "secure_password"

}

Response (200):

{
  "id": "uuid",
  "email": "user@example.com",
  "token": "jwt_token"

}

Error (401):

{
  "detail": "Invalid credentials"

}

Questions

GET /api/v1/questions

Получить список вопросов.

Query Parameters:

• page (int) — номер страницы
• limit (int) — кол-во элементов
• profession_id (uuid) — фильтр по профессии

Response:

{
  "total": 1500,
  "items": [

{
  "id": "uuid",
  "title": "Что такое React?",
  "difficulty": "easy"
}

  ]

}

### 5. Inline Documentation

В коде сам — комментарии для сложной логики:

```typescript
/**
 * Парсит URL параметры с поддержкой nested objects
 * @param searchParams - Next.js SearchParams
 * @returns Объект с распарсенными параметрами
 * 
 * @example
 * parseQueryParams('?profession=frontend&tags=react,typescript')
 * // { profession: 'frontend', tags: ['react', 'typescript'] }
 */
function parseQueryParams(searchParams: SearchParams) {
  // логика здесь
}

// Сложный расчет — объясни ЧТО и ПОЧЕМУ
const LCP_THRESHOLD = 2500; // Largest Contentful Paint, мс
// Берем 2.5s как порог Google CWV
const isLcpGood = lcpValue < LCP_THRESHOLD;

6. Changelog

CHANGELOG.md — история изменений:

# Changelog

## [2.1.0] - 2026-04-02

### Added
- Support for dark mode
- Keyboard shortcuts (Cmd+K for search)
- Spanish translation

### Fixed
- Login form not working on Safari
- Memory leak in useQuestions hook

### Changed
- Refactored component structure
- Updated Tailwind to v4

## [2.0.0] - 2026-03-15

### Breaking Changes
- Removed deprecated useAuth hook
- Changed API response structure

7. Troubleshooting Guide

docs/troubleshooting.md — типичные проблемы:

# Troubleshooting

## HydrationError in Next.js

**Проблема:** `Hydration failed because the server...`

**Решение:**
1. Проверь, что на клиенте и сервере одинаковые данные
2. Используй `useEffect` для client-only логики
3. Оберни в `<Suspense>`

```typescript

const ClientOnly = () => {

  const [mounted, setMounted] = useState(false);
  
  useEffect(() => setMounted(true), []);
  
  return mounted ? <RealComponent /> : null;

};

Slow Tests

Проблема: Jest тесты медленные

Решение:

1. Используй npm run test -- --maxWorkers=4
2. Избегай реальных HTTP запросов (используй mocks)
3. Проверь не создаёшь ли новые store для каждого теста

### 8. Tool Documentation

Когда добавляешь новый инструмент — документируй как его использовать:

```markdown
# Using Zustand for State

## Setup

```typescript

// stores/userStore.ts import { create } from 'zustand';

interface UserStore {
  user: User | null;
  setUser: (user: User) => void;

}

export const useUserStore = create<UserStore>((set) => ({

  user: null,
  setUser: (user) => set({ user })
}));

Usage

function Profile() {

  const user = useUserStore((state) => state.user);
  const setUser = useUserStore((state) => state.setUser);
  
  return <div>{user?.name}</div>;

}

Testing

const { result } = renderHook(() => useUserStore()); await act(() => result.current.setUser(mockUser)); expect(result.current.user).toEqual(mockUser);

### 9. Design System Documentation

**docs/design/** — UI компоненты и стиль:

```markdown
# Design System

## Colors

Все цвета из `globals.css`:

```css
@theme inline {
  --text-content-primary: #1a1a1a;
  --text-content-secondary: #666666;
  --bg-surface-primary: #ffffff;
  --border-border-default: #dddddd;

}

Button Component

Props

interface ButtonProps {
  variant?: 'primary' | 'secondary' | 'outline';
  size?: 'sm' | 'md' | 'lg';
  disabled?: boolean;
  children: React.ReactNode;

}

Examples

<Button variant="primary" size="lg">Save</Button>
<Button variant="secondary" disabled>Disabled</Button>
<Button variant="outline">Cancel</Button>

### 10. Как я веду документацию

#### Правила

1. **Живая документация** — обновляй когда меняется код
2. **Примеры кода** — всегда рабочие примеры, не псевдокод
3. **Организация** — четкая структура папок в docs/
4. **Индекс** — docs/INDEX.md ссылается на всё
5. **Версионирование** — указывай версии библиотек

#### Структура папок docs/

docs/ INDEX.md # главное оглавление guides/ # How-to гайды testing.md debugging.md architecture/ # архитектурные решения 01_structure.md 02_decisions.md api/ # API документация endpoints.md auth.md design/ # design system colors.md components.md

#### docs/INDEX.md

```markdown
# Documentation Index

## Getting Started
- [Installation](guides/installation.md)
- [Project Structure](architecture/01_structure.md)

## Development
- [Testing Strategy](guides/testing.md)
- [API Integration](api/endpoints.md)

## Architecture
- [Component Structure](architecture/01_structure.md)
- [Decisions Log](architecture/02_decisions.md)

11. CI/CD для документации

Проверяем что документация не мертва:

# Проверить что все ссылки живые
npm run docs:check-links

# Линтить markdown
npm run docs:lint

# Генерировать навигацию
npm run docs:build-index

Заключение

Хорошая документация — это инвестиция, которая окупается потом:

• Новые разработчики быстрее онбордятся
• Меньше вопросов в чате
• Меньше ошибок
• Проще поддерживать код

Документируй:

• Почему (decisions)
• Как (usage)
• Примеры (code samples)
• Ошибки (troubleshooting)