Generowanie dokumentacji - Cursor

Scenariusz

Twoja biblioteka open-source zyskała popularność z 10K gwiazdkami na GitHub, ale użytkownicy narzekają na słabą dokumentację. Musisz stworzyć referencje API, przewodniki użytkowania, dokumentację architektury, przewodniki migracji i interaktywne przykłady. Baza kodu obejmuje 50K linii ze złożonymi API, a potrzebujesz wszystkiego gotowego na duże wydanie v2.0 w przyszłym tygodniu.

Cele nauki

Po ukończeniu tej lekcji opanujesz:

• Generowanie dokumentacji wspomagane AI
• Tworzenie różnych typów dokumentacji
• Utrzymywanie świeżości dokumentacji
• Budowanie interaktywnej dokumentacji
• Automatyczne generowanie przykładów kodu
• Konfigurowanie pipeline’ów dokumentacji

Wymagania wstępne

• Zrozumienie typów dokumentacji
• Podstawowa znajomość markdown
• Ukończone poprzednie lekcje
• Znajomość narzędzi dokumentacji
• Opcjonalnie: Context7 MCP dla dokumentacji bibliotek (zobacz konfigurację)

Wyzwanie

Stwórz kompleksową dokumentację zawierającą:

• Kompletną referencę API
• Przewodniki rozpoczynania pracy
• Dokumentację architektury
• Przewodniki migracji
• Interaktywne przykłady
• Przeszukiwalną stronę dokumentacji

Wskazówka

AI doskonale analizuje wzorce kodu i generuje spójną dokumentację. Użyj go do stworzenia fundamentu, a następnie udoskonal ludzkim wglądem dla najlepszych rezultatów.

Implementacja z przewodnikiem

Faza 1: Analiza dokumentacji

1. Oceń obecną dokumentację

Zacznij od analizy tego co istnieje:

@src @docs
"Przeanalizuj obecny stan dokumentacji:
- Jaka dokumentacja istnieje?
- Co jest przestarzałe lub niepoprawne?
- Co całkowicie brakuje?
- Jak jest zorganizowana?
- Jakich formatów używa?
Stwórz raport analizy luk w dokumentacji"

2. Zdefiniuj architekturę dokumentacji

"Zaprojektuj kompleksową strukturę dokumentacji dla:
- Referencji API (automatycznie generowanej z kodu)
- Tutoriali (nauka oparta na zadaniach)
- Przewodników konceptualnych (zrozumienie systemu)
- Przewodników how-to (rozwiązywanie konkretnych problemów)
- Dokumentacji architektury (projekt systemu)
- Przewodnika kontrybuowania (dla open source)
Stwórz plan dokumentacji z priorytetami"

3. Skonfiguruj infrastrukturę dokumentacji

Przełącz na tryb Agent:

"Skonfiguruj nowoczesną infrastrukturę dokumentacji:
- Zainstaluj i skonfiguruj generator dokumentacji
- Skonfiguruj pipeline przetwarzania markdown
- Skonfiguruj podświetlanie składni
- Dodaj funkcjonalność wyszukiwania
- Skonfiguruj workflow wdrażania
Użyj Docusaurus lub podobnego narzędzia"

Przykład konfiguracji dokumentacji:

docusaurus.config.js

module.exports = {
  title: 'Dokumentacja MojejBiblioteki',
  tagline: 'Potężna, bezpieczna typowo i łatwa w użyciu',
  url: 'https://docs.mojabiblioteka.dev',
  baseUrl: '/',

  presets: [
    [
      '@docusaurus/preset-classic',
      {
        docs: {
          sidebarPath: require.resolve('./sidebars.js'),
          editUrl: 'https://github.com/mojaorg/mojabiblioteka/edit/main/',
          remarkPlugins: [
            require('remark-code-import'),
            require('remark-math'),
          ],
          rehypePlugins: [
            require('rehype-katex'),
          ],
        },
        theme: {
          customCss: require.resolve('./src/css/custom.css'),
        },
      },
    ],
  ],

  plugins: [
    [
      '@docusaurus/plugin-content-docs',
      {
        id: 'api',
        path: 'api',
        routeBasePath: 'api',
        sidebarPath: require.resolve('./sidebarsApi.js'),
      },
    ],
    '@docusaurus/plugin-ideal-image',
    [
      'docusaurus-plugin-typedoc',
      {
        entryPoints: ['../src/index.ts'],
        tsconfig: '../tsconfig.json',
        out: 'api',
        sidebar: {
          categoryLabel: 'Referencja API',
          position: 1,
        },
      },
    ],
  ],

  themeConfig: {
    navbar: {
      title: 'MojaBiblioteka',
      items: [
        {
          type: 'doc',
          docId: 'intro',
          position: 'left',
          label: 'Dokumenty',
        },
        {
          to: '/api',
          label: 'API',
          position: 'left',
        },
        {
          href: 'https://github.com/mojaorg/mojabiblioteka',
          label: 'GitHub',
          position: 'right',
        },
      ],
    },

    algolia: {
      appId: 'TWOJ_APP_ID',
      apiKey: 'TWOJ_SEARCH_API_KEY',
      indexName: 'mojabiblioteka',
    },

    prism: {
      theme: lightCodeTheme,
      darkTheme: darkCodeTheme,
      additionalLanguages: ['rust', 'elixir'],
    },
  },
};

Faza 1.5: Wykorzystanie Context7 MCP do dokumentacji

Zawsze aktualna dokumentacja

Context7 MCP zapewnia natychmiastowy dostęp do najnowszej dokumentacji dla 4000+ bibliotek. Użyj go, aby zapewnić że twoja dokumentacja odwołuje się do aktualnych API, porównaj swoją implementację z najlepszymi praktykami i znajdź przykłady z oficjalnych źródeł.

1. Skonfiguruj Context7 MCP

~/.cursor/mcp.json

{
  "mcpServers": {
    "context7": {
      "command": "npx",
      "args": ["-y", "@upstash/context7-mcp"]
    }
  }
}

2. Zbadaj obecne najlepsze praktyki

"Używając Context7 MCP, pokaż mi najnowsze:
- Wzorce dokumentacji React 18
- Standardy komentarzy dokumentacyjnych TypeScript 5
- Przykłady dokumentacji testowania Jest
- Struktury dokumentacji popularnych bibliotek"

// Uzyskaj dokumentację konkretnej biblioteki
"Używając Context7: Jak Next.js 14 dokumentuje:
- Trasy API
- Propsy komponentów
- Opcje konfiguracji
- Przewodniki migracji"

3. Generuj dokumentację na podstawie najnowszych standardów

Dokumentacja API

"Używając Context7, pokaż obecne standardy JSDoc dla:
- Funkcji asynchronicznych
- Typów generycznych
- Komponentów React
- Obsługi błędów

Następnie zastosuj do naszej bazy kodu"

Generowanie przykładów

"Używając Context7, znajdź przykłady:
- Poolingu połączeń z bazą danych
- Middleware uwierzytelniania
- Użycia hooków React
- Granic błędów

Dostosuj dla naszej dokumentacji"

Przewodniki migracji

"Używając Context7, przeanalizuj jak biblioteki obsługują:
- Dokumentację breaking changes
- Przewodniki migracji wersji
- Notacje deprecation
- Ścieżki upgrade'u"

4. Porównaj podejścia dokumentacyjne

"Używając Context7 MCP, porównaj style dokumentacji:
- React vs Vue dokumentacja komponentów
- Express vs Fastify dokumentacja API
- Prisma vs TypeORM dokumentacja schematów
Jakie wzorce działają najlepiej dla naszej biblioteki?"

// Uzyskaj konwencje specyficzne dla frameworka
"Używając Context7: Pokaż mi najlepsze praktyki Docusaurus dla:
- Struktury nawigacji
- Optymalizacji wyszukiwania
- Dokumentacji wersjonowanej
- Interaktywnych przykładów"

5. Bądź na bieżąco z zależnościami

"Używając Context7 MCP, sprawdź nasze zależności:
- Czy używamy przestarzałych API?
- Jaka jest ścieżka migracji dla przestarzałych metod?
- Które biblioteki mają główne aktualizacje?
- Jakie są nowe najlepsze praktyki?"

// Aktualizuj dokumentację odpowiednio
"Na podstawie ustaleń Context7, zaktualizuj naszą dokumentację aby:
- Odwoływać się do aktualnych metod API
- Używać nowoczesnych przykładów składni
- Podążać za najnowszymi konwencjami
- Zawierać ostrzeżenia o deprecation"

Wzorce dokumentacji Context7

Aktualizacje w czasie rzeczywistym:

"Używając Context7, co nowego w React Router v6.4+?
Zaktualizuj naszą dokumentację routingu aby odzwierciedlić:
- Nowe wzorce ładowania danych
- Zmiany w boundary błędów
- Aktualizacje konfiguracji tras"

Nauka międzybibliotekowa:

"Używając Context7, jak popularne biblioteki dokumentują:
- Przepływy uwierzytelniania (NextAuth, Auth0, Supabase)
- Zarządzanie stanem (Redux, Zustand, Jotai)
- Obsługę formularzy (React Hook Form, Formik)
Zastosuj najlepsze wzorce do naszej dokumentacji"

Dokumentacja świadoma wersji:

"Używając Context7, stwórz dokumentację specyficzną dla wersji:
- v1.x używając starego API
- v2.x z nowymi funkcjami
- Przewodnik migracji między wersjami
- Macierz kompatybilności"

Faza 2: Generowanie dokumentacji API

1. Generuj referencję API

@src
"Generuj kompleksową dokumentację API:
- Wyciągnij wszystkie publiczne API
- Dokumentuj parametry i typy zwracane
- Zawrzyj informacje o typach
- Dodaj przykłady użycia dla każdej metody
- Dokumentuj przypadki brzegowe i błędy
- Stwórz cross-referencje
Użyj formatu JSDoc/TSDoc"

Przykład wygenerowanej dokumentacji:

/**
 * Tworzy pulę połączeń dla operacji bazodanowych z automatyczną
 * logiką ponownych prób i recyklingiem połączeń.
 *
 * @example
 * ```typescript
 * // Podstawowe użycie
 * const pool = createPool({
 *   host: 'localhost',
 *   database: 'myapp',
 *   max: 20
 * });
 *
 * // Z opcjami zaawansowanymi
 * const pool = createPool({
 *   host: 'db.example.com',
 *   port: 5432,
 *   database: 'production',
 *   user: 'dbuser',
 *   password: process.env.DB_PASSWORD,
 *   max: 50,
 *   idleTimeoutMillis: 30000,
 *   connectionTimeoutMillis: 2000,
 *   retryAttempts: 3,
 *   retryDelay: 1000,
 *   ssl: {
 *     rejectUnauthorized: true,
 *     ca: fs.readFileSync('./ca-cert.pem')
 *   }
 * });
 *
 * // Używanie puli
 * const result = await pool.query('SELECT * FROM users WHERE id = $1', [userId]);
 * ```
 *
 * @param config - Opcje konfiguracji puli
 * @param config.host - Adres hosta bazy danych
 * @param config.port - Port bazy danych (domyślnie: 5432)
 * @param config.database - Nazwa bazy danych
 * @param config.user - Użytkownik bazy danych
 * @param config.password - Hasło bazy danych
 * @param config.max - Maksymalna liczba klientów w puli (domyślnie: 10)
 * @param config.idleTimeoutMillis - Timeout bezczynnego klienta (domyślnie: 10000)
 * @param config.connectionTimeoutMillis - Timeout połączenia (domyślnie: 0)
 * @param config.retryAttempts - Liczba prób ponownych (domyślnie: 3)
 * @param config.retryDelay - Opóźnienie między próbami w ms (domyślnie: 1000)
 * @param config.ssl - Konfiguracja SSL obiekt lub boolean
 *
 * @returns Skonfigurowana instancja puli bazy danych
 *
 * @throws {ConnectionError} Gdy nie można nawiązać połączenia z bazą danych
 * @throws {ConfigurationError} Gdy brakuje wymaganej konfiguracji
 * @throws {SSLError} Gdy konfiguracja SSL jest nieprawidłowa
 *
 * @see {@link Pool} dla metod instancji puli
 * @see {@link query} dla wykonywania zapytań
 * @see {@link transaction} dla wsparcia transakcji
 *
 * @since 1.0.0
 * @public
 */
export function createPool(config: PoolConfig): Pool {
  validateConfig(config);

  const pool = new Pool({
    ...defaultConfig,
    ...config,
    // Wrapper logiki ponownych prób
    Client: createRetryableClient(config),
  });

  // Dodaj obsługę zdarzeń
  pool.on('error', (err, client) => {
    logger.error('Nieoczekiwany błąd bezczynnego klienta', err);
  });

  pool.on('connect', (client) => {
    logger.debug('Nowy klient podłączony do puli');
  });

  return wrapPoolMethods(pool);
}

/**
 * Opcje konfiguracji puli
 * @public
 */
export interface PoolConfig {
  /** Adres hosta bazy danych */
  host: string;

  /** Port bazy danych @defaultValue 5432 */
  port?: number;

  /** Nazwa bazy danych */
  database: string;

  /** Użytkownik bazy danych */
  user?: string;

  /** Hasło bazy danych */
  password?: string;

  /**
   * Maksymalna liczba klientów w puli
   * @defaultValue 10
   * @remarks
   * Rozważ limity połączeń twojej bazy danych przy ustawianiu tej wartości.
   * Każdy klient zużywa zasoby zarówno na serwerze aplikacji jak i bazy danych.
   */
  max?: number;

  /**
   * Liczba milisekund które klient musi być bezczynny przed zamknięciem
   * @defaultValue 10000
   */
  idleTimeoutMillis?: number;

  /**
   * Liczba milisekund oczekiwania przed timeout przy łączeniu
   * @defaultValue 0 (bez timeout)
   */
  connectionTimeoutMillis?: number;

  /**
   * Liczba prób ponownych nieudanych połączeń
   * @defaultValue 3
   */
  retryAttempts?: number;

  /**
   * Opóźnienie między próbami ponownych połączeń w milisekundach
   * @defaultValue 1000
   */
  retryDelay?: number;

  /**
   * Konfiguracja SSL
   * @example
   * ```typescript
   * // Włącz SSL z domyślnymi ustawieniami
   * ssl: true
   *
   * // Niestandardowa konfiguracja SSL
   * ssl: {
   *   rejectUnauthorized: true,
   *   ca: fs.readFileSync('./ca-cert.pem'),
   *   key: fs.readFileSync('./client-key.pem'),
   *   cert: fs.readFileSync('./client-cert.pem')
   * }
   * ```
   */
  ssl?: boolean | SSLConfig;
}

2. Generuj dokumentację typów

@src/types
"Dokumentuj wszystkie typy i interfejsy TypeScript:
- Wyciągnij definicje typów
- Dokumentuj parametry typów
- Pokaż hierarchię dziedziczenia
- Stwórz przykłady użycia typów
- Dokumentuj związki dyskryminowane
- Dodaj przykłady type guards"

3. Stwórz przykłady kodu

@src @tests
"Generuj przykłady kodu dla wszystkich głównych funkcji:
- Przykłady podstawowego użycia
- Zaawansowane wzorce
- Przykłady obsługi błędów
- Przykłady optymalizacji wydajności
- Przykłady integracji
- Przykłady pełnych aplikacji
Wyciągnij z testów gdzie to możliwe"

Faza 3: Tworzenie tutoriali i przewodników

1. Generuj przewodnik rozpoczynania pracy

@src @examples
"Stwórz kompleksowy przewodnik rozpoczynania pracy:
- Instrukcje instalacji (npm, yarn, pnpm)
- Podstawowa konfiguracja i setup
- Pierwszy prosty przykład
- Częste przypadki użycia
- Sekcja rozwiązywania problemów
- Następne kroki
Zrób go przyjaznym dla początkujących ale kompleksowym"

Przykład przewodnika rozpoczynania pracy:

# Rozpoczynanie pracy z MojąBiblioteką

## Instalacja

MojaBiblioteka może być zainstalowana używając twojego ulubionego menedżera pakietów:

```bash
# npm
npm install mojabiblioteka

# yarn
yarn add mojabiblioteka

# pnpm
pnpm add mojabiblioteka

Podstawowa konfiguracja

1. Zaimportuj bibliotekę

// Moduły ES (zalecane)
import { createPool, query } from 'mojabiblioteka';

// CommonJS
const { createPool, query } = require('mojabiblioteka');

2. Stwórz swoje pierwsze połączenie

import { createPool } from 'mojabiblioteka';

// Stwórz pulę połączeń
const pool = createPool({
  host: 'localhost',
  database: 'myapp',
  user: 'myuser',
  password: 'mypassword'
});

// Przetestuj połączenie
try {
  const result = await pool.query('SELECT NOW()');
  console.log('Połączono pomyślnie:', result.rows[0]);
} catch (error) {
  console.error('Połączenie nieudane:', error);
}

3. Wykonaj swoje pierwsze zapytanie

// Proste zapytanie
const users = await pool.query('SELECT * FROM users');
console.log(`Znaleziono ${users.rowCount} użytkowników`);

// Zapytanie sparametryzowane (zapobiega SQL injection)
const userId = 123;
const user = await pool.query(
  'SELECT * FROM users WHERE id = $1',
  [userId]
);

// Używanie query buildera
const activeUsers = await pool
  .select('id', 'name', 'email')
  .from('users')
  .where('active', true)
  .orderBy('created_at', 'DESC')
  .limit(10)
  .execute();

Częste wzorce

Zarządzanie połączeniami

// Automatyczne zarządzanie połączeniami
async function getUser(id: number) {
  // Połączenie jest automatycznie nabywane i zwalniane
  return pool.query('SELECT * FROM users WHERE id = $1', [id]);
}

// Manualne zarządzanie połączeniami dla transakcji
async function transferFunds(from: number, to: number, amount: number) {
  const client = await pool.connect();

  try {
    await client.query('BEGIN');

    await client.query(
      'UPDATE accounts SET balance = balance - $1 WHERE id = $2',
      [amount, from]
    );

    await client.query(
      'UPDATE accounts SET balance = balance + $1 WHERE id = $2',
      [amount, to]
    );

    await client.query('COMMIT');
  } catch (error) {
    await client.query('ROLLBACK');
    throw error;
  } finally {
    client.release();
  }
}

Obsługa błędów

import { DatabaseError, ConnectionError } from 'mojabiblioteka';

try {
  const result = await pool.query('SELECT * FROM users');
} catch (error) {
  if (error instanceof ConnectionError) {
    console.error('Połączenie z bazą danych nieudane:', error.message);
    // Implementuj logikę ponownych prób lub fallback
  } else if (error instanceof DatabaseError) {
    console.error('Zapytanie nieudane:', error.message);
    // Loguj szczegóły zapytania dla debugowania
  } else {
    console.error('Nieoczekiwany błąd:', error);
  }
}

Opcje konfiguracji

Konfiguracja oparta na środowisku

const pool = createPool({
  host: process.env.DB_HOST || 'localhost',
  port: parseInt(process.env.DB_PORT || '5432'),
  database: process.env.DB_NAME || 'development',
  user: process.env.DB_USER,
  password: process.env.DB_PASSWORD,
  max: parseInt(process.env.DB_POOL_SIZE || '10'),
  // Włącz SSL w produkcji
  ssl: process.env.NODE_ENV === 'production'
});

Zaawansowana konfiguracja

const pool = createPool({
  // Ustawienia połączenia
  host: 'db.example.com',
  port: 5432,
  database: 'production',

  // Ustawienia puli
  max: 20,                      // Maksymalny rozmiar puli
  min: 5,                       // Minimalny rozmiar puli
  idleTimeoutMillis: 30000,     // Zamknij bezczynnych klientów po 30s
  connectionTimeoutMillis: 2000, // Timeout nowych połączeń po 2s

  // Ustawienia ponownych prób
  retryAttempts: 3,
  retryDelay: 1000,

  // Monitoring
  onConnect: (client) => {
    console.log('Klient połączony');
  },
  onError: (error, client) => {
    console.error('Błąd puli:', error);
  }
});

Rozwiązywanie problemów

Częste problemy

Timeout połączenia

// Zwiększ timeout połączenia
const pool = createPool({
  connectionTimeoutMillis: 5000, // 5 sekund
  // ... pozostała konfiguracja
});

Za dużo połączeń

// Monitoruj użycie puli
console.log('Łączna liczba klientów:', pool.totalCount);
console.log('Bezczynni klienci:', pool.idleCount);
console.log('Oczekujące żądania:', pool.waitingCount);

// Dostosuj rozmiar puli na podstawie użycia
const pool = createPool({
  max: 50, // Zwiększ maksymalną liczbę połączeń
  // ... pozostała konfiguracja
});

Problemy z połączeniem SSL

// Debuguj połączenia SSL
const pool = createPool({
  ssl: {
    rejectUnauthorized: false, // Tylko dla developmentu!
    // Dla produkcji, dostarcz odpowiednie certyfikaty
    ca: fs.readFileSync('./server-ca.pem'),
  }
});

Następne kroki

Teraz gdy masz MojąBibliotekę działającą:

1. Eksploruj zaawansowane funkcje

   • Przewodnik Query Builder
   • Zarządzanie transakcjami
   • Głębokie zanurzenie w Connection Pooling

2. Najlepsze praktyki

   • Wytyczne bezpieczeństwa
   • Optymalizacja wydajności
   • Wzorce obsługi błędów

3. Przewodniki integracji

   • Integracja Express.js
   • Integracja Next.js
   • Strategie testowania

Potrzebujesz pomocy?

• 📚 Przeczytaj pełną dokumentację
• 💬 Dołącz do naszej społeczności Discord
• 🐛 Zgłoś problemy na GitHub
• 🎯 Sprawdź przykłady

2. **Stwórz przewodniki tematyczne**

```typescript
"Generuj szczegółowe przewodniki dla konkretnych tematów:
- Wzorce uwierzytelniania
- Optymalizacja wydajności
- Strategie obsługi błędów
- Podejścia do testowania
- Przewodniki wdrażania
- Najlepsze praktyki bezpieczeństwa
Każdy przewodnik powinien być kompleksowy i praktyczny"

3. Zbuduj interaktywne przykłady

"Stwórz interaktywną dokumentację:
- Playground'y żywego kodu
- Przykłady do uruchomienia
- Interaktywny eksplorator API
- Tutoriale krok po kroku
- Demonstracje wideo
Użyj CodeSandbox lub podobnego"

Faza 4: Dokumentacja architektury

1. Generuj diagramy architektury

@src
"Stwórz dokumentację architektury:
- Diagram przeglądu systemu
- Relacje komponentów
- Diagramy przepływu danych
- Diagramy sekwencji dla kluczowych przepływów
- Architektura wdrożenia
Użyj Mermaid lub PlantUML"

Przykład dokumentacji architektury:

# Architektura systemu

## Przegląd

MojaBiblioteka podąża za modularną architekturą zaprojektowaną dla skalowalności i łatwości utrzymania.

```mermaid
graph TB
    subgraph "Warstwa aplikacji"
        APP[Twoja aplikacja]
    end

    subgraph "Rdzeń MojejBiblioteki"
        API[Publiczne API]
        QM[Menedżer zapytań]
        PM[Menedżer puli]
        CM[Menedżer połączeń]
        RM[Menedżer ponownych prób]
    end

    subgraph "Warstwa bazy danych"
        PG[(PostgreSQL)]
        MY[(MySQL)]
        MS[(SQL Server)]
    end

    APP --> API
    API --> QM
    API --> PM
    QM --> CM
    PM --> CM
    CM --> RM
    RM --> PG
    RM --> MY
    RM --> MS

Komponenty rdzeniowe

Menedżer puli

Odpowiedzialny za zarządzanie pulami połączeń z bazą danych:

• Zarządzanie cyklem życia połączeń
• Dobieranie rozmiaru i optymalizacja puli
• Monitoring zdrowia
• Zbieranie metryk

Menedżer zapytań

Obsługuje wykonywanie i optymalizację zapytań:

• Parsowanie i walidacja zapytań
• Wiązanie parametrów
• Transformacja wyników
• Cachowanie zapytań

Menedżer połączeń

Obsługa połączeń niskiego poziomu:

• Implementacja protokołu
• Negocjacja SSL/TLS
• Uwierzytelnianie
• Zarządzanie keep-alive

Menedżer ponownych prób

Implementuje wzorce odporności:

• Exponential backoff
• Circuit breaker
• Obsługa timeout
• Klasyfikacja błędów

Przepływ żądań

sequenceDiagram participant App participant API participant Pool participant Connection participant Database App->>API: query(sql, params) API->>Pool: getConnection() alt Połączenie dostępne Pool->>API: connection else Pula wyczerpana Pool->>API: czekaj w kolejce Pool->>API: connection (gdy dostępne) end API->>Connection: execute(sql, params) Connection->>Database: wyślij zapytanie Database->>Connection: wynik Connection->>API: przekształcony wynik API->>Pool: release(connection) API->>App: wynik

Zasady projektowe

1. Rdzeń bez zależności

Podstawowa funkcjonalność nie ma zewnętrznych zależności, zapewniając:

• Minimalny rozmiar bundle
• Ograniczoną powierzchnię bezpieczeństwa
• Łatwiejsze utrzymanie
• Lepszą wydajność

2. Architektura wtyczek

Rozszerzona funkcjonalność przez wtyczki:

import { createPool } from 'mojabiblioteka';
import { metricsPlugin } from 'mojabiblioteka-metrics';
import { cachingPlugin } from 'mojabiblioteka-cache';

const pool = createPool({
  // ... konfiguracja
  plugins: [
    metricsPlugin({ provider: 'prometheus' }),
    cachingPlugin({ ttl: 300 })
  ]
});

3. Bezpieczeństwo typów

Pełne wsparcie TypeScript z:

• Wnioskowanymi wynikami zapytań
• Bezpiecznymi typowo query builderami
• Walidacją w czasie kompilacji
• Wsparciem auto-completion

2. **Dokumentuj decyzje projektowe**

```typescript
"Stwórz ADR (Architecture Decision Records):
- Kluczowe decyzje projektowe
- Rozważane alternatywy
- Uzasadnienie wyborów
- Zaakceptowane kompromisy
- Strategie migracji
Podążaj za szablonem ADR"

3. Dokumentacja wydajności

"Dokumentuj charakterystyki wydajności:
- Wyniki benchmarków
- Techniki optymalizacji
- Strategie skalowania
- Wymagania zasobowe
- Analiza wąskich gardeł
Zawrzyj rzeczywiste pomiary"

Faza 5: Automatyzacja dokumentacji

1. Skonfiguruj pipeline auto-generowania

"Stwórz zautomatyzowany pipeline dokumentacji:
- Wyciągnij dokumentację z kodu źródłowego
- Generuj przy każdym commit
- Aktualizuj dokumentację specyficzną dla wersji
- Wdrażaj na stronę dokumentacji
- Powiadamiaj o breaking changes
Użyj GitHub Actions"

Przykład workflow automatyzacji:

.github/workflows/docs.yml

name: Dokumentacja

on:
  push:
    branches: [main]
    paths:
      - 'src/**'
      - 'docs/**'
  pull_request:
    branches: [main]

jobs:
  generate-docs:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v3

      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '18'
          cache: 'npm'

      - name: Zainstaluj zależności
        run: npm ci

      - name: Generuj dokumentację API
        run: |
          npm run docs:api
          npm run docs:types

      - name: Sprawdź pokrycie dokumentacji
        run: |
          npm run docs:coverage
          # Niepowodzenie jeśli pokrycie < 90%

      - name: Generuj przykłady z testów
        run: npm run docs:examples

      - name: Zbuduj stronę dokumentacji
        run: npm run docs:build

      - name: Uruchom testy dokumentacji
        run: |
          # Testuj wszystkie przykłady kodu
          npm run docs:test-examples

          # Sprawdź zepsute linki
          npm run docs:check-links

      - name: Wdróż na GitHub Pages
        if: github.ref == 'refs/heads/main'
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./docs/build

      - name: Zaktualizuj indeks wyszukiwania
        if: github.ref == 'refs/heads/main'
        run: |
          npm run docs:update-search
        env:
          ALGOLIA_API_KEY: ${{ secrets.ALGOLIA_API_KEY }}

2. Stwórz testy dokumentacji

"Stwórz testy dla dokumentacji:
- Waliduj kompilację przykładów kodu
- Testuj wyjścia przykładów
- Sprawdź kompletność API
- Weryfikuj integralność linków
- Zapewnij spójność wersji
Uruchamiaj w CI/CD"

3. Zbuduj metryki dokumentacji

"Stwórz metryki jakości dokumentacji:
- Procent pokrycia
- Wskaźniki świeżości
- Kompletność przykładów
- Skuteczność wyszukiwania
- Integracja opinii użytkowników
Wyświetl w dashboardzie"

Kluczowe techniki zademonstrowane

Technika 1: Badania dokumentacyjne wspomagane MCP

Użyj Context7 aby być na bieżąco:

// Badania przed dokumentowaniem
"Używając Context7 MCP, zbadaj:
- Jak React dokumentuje hooki?
- Jaki jest standard TypeScript dla generyków?
- Jak popularne ORM dokumentują zapytania?"

// Waliduj względem obecnych standardów
"Używając Context7, zweryfikuj że nasze przykłady używają:
- Najnowszej składni (ES2024+)
- Aktualnych wersji bibliotek
- Nowoczesnych najlepszych praktyk
- Nieprzdestarzałych API"

// Znajdź inspirację dokumentacyjną
"Używając Context7, pokaż mi doskonałą dokumentację dla:
- Ograniczania szybkości API
- Połączeń WebSocket
- Przepływów uwierzytelniania
Użyj jako szablonów dla naszej dokumentacji"

Technika 2: Dokumentacja jako kod

Traktuj dokumentację jak kod:

src/database/pool.ts

/**
 * @example <caption>Podstawowa pula połączeń</caption>
 * ```typescript
 * const pool = createPool({
 *   host: 'localhost',
 *   database: 'myapp'
 * });
 * ```
 *
 * @example <caption>Konfiguracja produkcyjna</caption>
 * ```typescript
 * const pool = createPool({
 *   host: process.env.DB_HOST,
 *   database: process.env.DB_NAME,
 *   max: 50,
 *   ssl: true
 * });
 * ```
 */
export function createPool(config: PoolConfig): Pool {
  // Implementacja
}

Technika 3: Żywa dokumentacja

Utrzymuj dokumentację zsynchronizowaną z kodem:

// Generuj dokumentację z testów
describe('createPool', () => {
  it('tworzy podstawową pulę', () => {
    // @doc-example: basic-pool
    const pool = createPool({
      host: 'localhost',
      database: 'test'
    });

    expect(pool).toBeDefined();
    // @end-doc-example
  });
});

Technika 4: Progresywna dokumentacja

Warstwy informacji dla różnych odbiorców:

Query Builder

Początkujący

// Proste zapytanie select
const users = await db
  .select('*')
  .from('users')
  .execute();

Średnio zaawansowany

// Złożone zapytanie z join'ami
const posts = await db
  .select('posts.*', 'users.name as author')
  .from('posts')
  .join('users', 'posts.user_id', 'users.id')
  .where('posts.published', true)
  .orderBy('posts.created_at', 'DESC')
  .limit(10)
  .execute();

Zaawansowany

// Dynamiczne budowanie zapytań
const query = db.select().from('products');

if (filters.category) {
  query.where('category', filters.category);
}

if (filters.priceRange) {
  query.whereBetween('price',
    [filters.priceRange.min, filters.priceRange.max]
  );
}

const results = await query
  .orderBy(sortField, sortOrder)
  .paginate(page, perPage);

Częste problemy dokumentacyjne

Przestarzałe przykłady

Problem: Przykłady kodu już nie działają

Rozwiązanie:

// Testuj wszystkie przykłady automatycznie
import { extractExamples } from './docs-utils';

describe('Przykłady dokumentacji', () => {
  const examples = extractExamples('./docs');

  test.each(examples)('$name powinien działać bez błędów',
    async ({ code }) => {
      const result = await runExample(code);
      expect(result.error).toBeUndefined();
    }
  );
});

Brakujący kontekst

Problem: Przykładom brakuje niezbędnej konfiguracji

Rozwiązanie:

## Kompletny przykład

```typescript
// Wymagane importy
import { createPool } from 'mojabiblioteka';
import dotenv from 'dotenv';

// Załaduj zmienne środowiskowe
dotenv.config();

// Stwórz pulę z obsługą błędów
async function setupDatabase() {
  try {
    const pool = createPool({
      host: process.env.DB_HOST,
      database: process.env.DB_NAME,
      user: process.env.DB_USER,
      password: process.env.DB_PASSWORD
    });

    // Przetestuj połączenie
    await pool.query('SELECT 1');
    console.log('Baza danych połączona');

    return pool;
  } catch (error) {
    console.error('Połączenie z bazą danych nieudane:', error);
    process.exit(1);
  }
}

// Użyj w aplikacji
const pool = await setupDatabase();

Słaba przeszukiwalność

Problem: Użytkownicy nie mogą znaleźć tego czego potrzebują

Rozwiązanie:

// Dodaj metadane wyszukiwania
/**
 * @keywords connection, pool, database, postgres, mysql
 * @category Database
 * @since 1.0.0
 */

// Stwórz synonimy wyszukiwania
const searchSynonyms = {
  'connect': ['connection', 'pool', 'client'],
  'query': ['select', 'insert', 'update', 'delete', 'sql'],
  'error': ['exception', 'failure', 'problem']
};

Rozszerzone wyzwanie

Zaawansowane funkcje dokumentacji:

1. Internacjonalizacja

   • Wielojęzyczna dokumentacja
   • Automatyczne tłumaczenie
   • Przykłady specyficzne dla lokalizacji
   • Wsparcie języków RTL

2. Interaktywna nauka

   • Osadzone playground’y kodu
   • Interaktywne tutoriale
   • Śledzenie postępów
   • System certyfikacji

3. Funkcje wspomagane AI

   • Inteligentne wyszukiwanie z NLP
   • Automatyczne generowanie FAQ
   • Sugestie przykładów kodu
   • Spersonalizowane ścieżki nauki

4. Dokumentacja wzbogacona MCP

   • Użyj Context7 dla aktualizacji API w czasie rzeczywistym
   • Zintegruj Notion MCP dla wspólpracujących dokumentów
   • Dodaj GitHub MCP dla synchronizacji przykładów kodu
   • Stwórz niestandardowy MCP dla wewnętrznej bazy wiedzy

Mierzenie sukcesu

Twoja dokumentacja odnosi sukces gdy:

• ✅ Osiągnięto 100% pokrycia API
• ✅ Wszystkie przykłady przetestowane i działające
• ✅ Wyszukiwanie zwraca odpowiednie wyniki
• ✅ Nowi użytkownicy produktywni w mniej niż 30 min
• ✅ Zgłoszenia wsparcia zmniejszone o 70%
• ✅ Kontrybuicje społeczności wzrosły
• ✅ Dokumentacja pozostaje aktualna
• ✅ Użytkownicy oceniają dokumentację na 4.5+ gwiazdek

Wpływ w świecie rzeczywistym

Projekty z świetną dokumentacją raportują:

• 80% mniej pytań wsparcia
• 3x szybsze wdrażanie użytkowników
• 5x więcej kontrybucji społeczności
• 90% wyższą satysfakcję użytkowników

Lista kontrolna dokumentacji

Przed publikacją:

• Referencja API kompletna
• Przewodnik rozpoczynania pracy przetestowany przez nowicjusza
• Wszystkie przykłady działają pomyślnie
• Indeks wyszukiwania zaktualizowany
• Linki zweryfikowane
• Kompatybilność wersji odnotowana
• Wskazówki wydajności zawarte
• Sekcja rozwiązywania problemów gotowa

Kluczowe wnioski

1. Automatyzuj wszystko: Generuj dokumentację z kodu
2. Testuj dokumentację: Traktuj dokumentację jak kod
3. Warstwowa informacja: Obsługuj wszystkie poziomy umiejętności
4. Utrzymuj świeżość: Automatyzuj aktualizacje
5. Mierz użycie: Śledź co pomaga użytkownikom

Inwestycja czasu

• Początkowa konfiguracja: 2 godziny
• Dokumentacja API: 3 godziny
• Przewodniki i tutoriale: 4 godziny
• Dokumentacja architektury: 2 godziny
• Konfiguracja automatyzacji: 2 godziny
• Razem: ~13 godzin (oszczędza setki godzin wsparcia)

Następne kroki

Opanowałeś generowanie dokumentacji. Kontynuuj swoją podróż:

Tutoriale wideo

Twórz angażującą dokumentację wideo

Eksplorator API

Zbuduj interaktywny playground API

Przewodnik kontrybuowania

Umożliw dokumentację społecznościową

Kontynuuj do Następnej lekcji →

Wskazówka

Stwórz “Przewodnik stylu dokumentacji”, który definiuje twój głos, strukturę i format przykładów. Zawrzyj szablony dla częstych typów dokumentacji. To zapewnia spójność w miarę rozwoju projektu i większej liczby kontrybutorów.