12. Documentação

A documentação é um componente crítico no desenvolvimento de software, facilitando a manutenção, onboarding de novos desenvolvedores e uso eficiente de nossas APIs e sistemas. Esta seção fornece diretrizes detalhadas para criar e manter documentação de alta qualidade em todos os aspectos de nossos projetos.

12.1. Documentação de API

A documentação de API é essencial para desenvolvedores internos e externos que consomem nossos serviços.

12.1.1. Swagger/OpenAPI

Utilizamos Swagger/OpenAPI para documentar nossas APIs RESTful.

Para Laravel:

1. Instale o pacote darkaonline/l5-swagger:

composer require darkaonline/l5-swagger

2. Anote seus controllers:

/**
 * @OA\Info(title="My API", version="0.1")
 */
class Controller extends BaseController
{
    /**
     * @OA\Get(
     *     path="/api/users",
     *     summary="List users",
     *     @OA\Response(response="200", description="List of users")
     * )
     */
    public function index()
    {
        // Implementation
    }
}

3. Gere a documentação:

php artisan l5-swagger:generate

Para Node.js:

1. Instale o pacote swagger-jsdoc:

npm install swagger-jsdoc swagger-ui-express

2. Anote suas rotas:

/**
 * @swagger
 * /api/users:
 *   get:
 *     summary: List users
 *     responses:
 *       200:
 *         description: List of users
 */
app.get('/api/users', (req, res) => {
  // Implementation
});

3. Configure o Swagger:

const swaggerJsdoc = require('swagger-jsdoc');
const swaggerUi = require('swagger-ui-express');
 
const options = {
  definition: {
    openapi: '3.0.0',
    info: {
      title: 'My API',
      version: '1.0.0',
    },
  },
  apis: ['./routes/*.js'],
};
 
const specs = swaggerJsdoc(options);
app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(specs));

12.1.2. Portal de APIs

Implemente um portal de APIs centralizado usando ferramentas como Postman, Stoplight, ou uma solução personalizada.

1. Organize APIs por serviço ou domínio.
2. Inclua exemplos de requisição e resposta.
3. Forneça SDKs ou snippets de código para linguagens comuns.
4. Mantenha um changelog visível.

12.2. Documentação de usuário

A documentação de usuário deve ser clara, concisa e orientada para o público-alvo.

Diretrizes

1. Use linguagem simples e direta.
2. Inclua muitos exemplos e casos de uso.
3. Utilize screenshots e vídeos para ilustrar processos.
4. Organize o conteúdo de forma lógica e fácil de navegar.
5. Mantenha um FAQ atualizado.

Ferramentas recomendadas

• GitBook para documentação técnica e guias de usuário.
• Loom para vídeos tutoriais rápidos.
• Confluence para documentação interna e colaborativa.

12.3. Documentação técnica

A documentação técnica é crucial para a manutenção e evolução do projeto.

12.3.1. Documentação de código

Para PHP/Laravel:

Use PHPDoc para documentar classes, métodos e propriedades:

/**
 * User Model
 *
 * @property int $id
 * @property string $name
 * @property string $email
 * @property \DateTime $created_at
 *
 * @method static \Illuminate\Database\Eloquent\Builder|User newModelQuery()
 * @method static \Illuminate\Database\Eloquent\Builder|User newQuery()
 * @method static \Illuminate\Database\Eloquent\Builder|User query()
 */
class User extends Model
{
    /**
     * Create a new user.
     *
     * @param string $name User's full name
     * @param string $email User's email address
     * @return User
     * @throws \InvalidArgumentException If email is invalid
     */
    public static function createUser(string $name, string $email): User
    {
        // Implementation
    }
}

Para Node.js:

Use JSDoc para JavaScript e TSDoc para TypeScript:

/**
 * Represents a user in the system.
 * @typedef {Object} User
 * @property {number} id - The user's unique identifier.
 * @property {string} name - The user's full name.
 * @property {string} email - The user's email address.
 */
 
/**
 * Creates a new user.
 * @param {string} name - The user's full name.
 * @param {string} email - The user's email address.
 * @returns {Promise<User>} The created user object.
 * @throws {Error} If the email is invalid.
 */
async function createUser(name, email) {
  // Implementation
}

12.4. Documentação de banco de dados

A documentação adequada do banco de dados é crucial para a manutenção, escalabilidade e compreensão do sistema a longo prazo.

12.4.1. Comentários em tabelas do banco de dados

Toda tabela do banco de dados deve ter um comentário detalhado. Estes comentários devem:

1. Descrever o propósito da tabela.
2. Explicar suas relações com outras tabelas.
3. Detalhar como a tabela funciona e interage com outras partes do sistema.
4. Ser suficientemente detalhados para serem utilizados no treinamento de modelos de linguagem e IA para interação com o banco de dados.

Exemplo de como adicionar um comentário a uma tabela usando Laravel:

Schema::create('users', function (Blueprint $table) {
    $table->id();
    $table->string('name');
    $table->string('email')->unique();
    $table->timestamp('email_verified_at')->nullable();
    $table->string('password');
    $table->rememberToken();
    $table->timestamps();
 
    $table->comment('
        Armazena informações dos usuários do sistema.
        Relações:
        - Um usuário pode ter muitos posts (one-to-many com "posts").
        - Um usuário pode ter muitos comentários (one-to-many com "comments").
        Campos importantes:
        - email: Usado para login e comunicações. Deve ser único.
        - email_verified_at: Null indica email não verificado.
        Observações:
        - Considerar adicionar campos para perfil (ex: avatar, bio) no futuro.
        - A exclusão de um usuário deve ser gerenciada cuidadosamente devido às relações.
    ');
});

Este método é suportado por MariaDB, MySQL e PostgreSQL.

12.4.2. Compatibilidade com PostgreSQL

É explicitamente proibido utilizar schemas ou padrões de schema que sejam incompatíveis com PostgreSQL. Esta medida visa facilitar a futura migração de MySQL para PostgreSQL.

12.5.2. Documentação de arquitetura

1. Mantenha diagramas de arquitetura atualizados (use ferramentas como draw.io ou Mermaid).
2. Documente decisões de arquitetura usando ADRs (Architecture Decision Records).
3. Mantenha um glossário de termos técnicos e de domínio.

Exemplo de ADR:

# 1. Uso de Redis para Cache
 
Data: 2023-05-15
 
## Status
 
Aceito
 
## Contexto
 
Precisamos de uma solução de cache para melhorar a performance da aplicação.
 
## Decisão
 
Decidimos usar Redis como nossa solução de cache.
 
## Consequências
 
Positivas:
- Alta performance
- Suporte a estruturas de dados complexas
 
Negativas:
- Necessidade de gerenciar um serviço adicional
- Curva de aprendizado para a equipe

12.4. Manutenção e atualização da documentação

A documentação desatualizada é frequentemente pior que nenhuma documentação.

Diretrizes para manutenção

1. Trate a documentação como código:

   • Mantenha-a no controle de versão.
   • Faça revisões de documentação parte do processo de code review.

2. Automatize quando possível:

   • Use ferramentas que geram documentação a partir de comentários no código.
   • Implemente testes que falham quando a documentação está desatualizada.

3. Estabeleça um processo de revisão regular:

   • Agende revisões trimestrais da documentação.
   • Atribua "proprietários" para diferentes seções da documentação.

4. Incentive contribuições:

   • Torne fácil para qualquer membro da equipe sugerir melhorias na documentação.
   • Reconheça contribuições significativas para a documentação.

5. Integre a atualização da documentação no ciclo de desenvolvimento:

   • Inclua "Atualizar documentação" como parte da Definition of Done para tarefas.

Ferramentas e práticas recomendadas

1. Use Markdown para documentação que será versionada com o código.
2. Implemente hooks de pre-commit para verificar links quebrados na documentação.
3. Use ferramentas de linting para manter consistência no estilo da documentação.

Exemplo de script de verificação de links (Node.js):

const markdownLinkCheck = require('markdown-link-check');
const glob = require('glob');
const fs = require('fs');
 
glob('docs/**/*.md', (err, files) => {
  files.forEach(file => {
    const markdown = fs.readFileSync(file).toString();
    markdownLinkCheck(markdown, (err, results) => {
      results.forEach(result => {
        if (result.status === 'dead') {
          console.log(`Dead link in ${file}: ${result.link}`);
        }
      });
    });
  });
});

Diretrizes adicionais

1. Consistência: Mantenha um estilo consistente em toda a documentação.

2. Acessibilidade: Garanta que a documentação seja acessível, seguindo as diretrizes WCAG.

3. Multilíngue: Para projetos internacionais, considere manter a documentação em múltiplos idiomas.

4. Feedback: Implemente um sistema para coletar feedback dos usuários da documentação.

5. Versionamento: Mantenha versões da documentação alinhadas com as versões do software.

Responsabilidades da equipe

1. Desenvolvedores:

   • Documentar código e APIs à medida que são desenvolvidos.
   • Atualizar a documentação existente ao fazer alterações.

2. Tech Leads:

   • Revisar a qualidade e completude da documentação.
   • Garantir que a documentação seja parte integral do processo de desenvolvimento.

3. Product Owners:

   • Fornecer input para documentação de usuário e guias de produto.
   • Validar a clareza da documentação do ponto de vista do usuário.

4. QA:

   • Verificar se a documentação reflete com precisão o comportamento real do sistema.
   • Incluir testes de documentação no processo de QA.

Lembre-se: Documentação eficaz é um investimento que paga dividendos em termos de eficiência da equipe, satisfação do usuário e manutenibilidade do projeto a longo prazo. Trate a documentação com o mesmo cuidado e atenção que você dedica ao código.