# Forma y estilo de la documentación

Toda la documentación se escribirá en Markdown, HTML o una combinación de ambos.

<div class="alert alert-primary">Toda la redacción técnica debe escribirse en <strong>Segunda persona del singular</strong> ("Usted", pero omitiendo el pronombre siempre que sea posible )</div>

Ejemplos:

```
Usted deberá agregar el archivo. -- INNECESARIO

Deberá agregar el archivo. -- MEJOR

```


## Documentación técnica de paquetes

El objetivo de esta documentación es proporcionar a desarrolladores y técnicos 
información utilizada o definida por todos los programas y elementos del paquete.

Debe seguirse la siguiente estructura:

* Nombre del paquete
* Repositorio
* Descripción general (Tipo de paquete, ¿Qué es? ¿Para qué? ¿Por qué?)
* Variables de configuración
* Tareas (opcional)
* Servicios (opcional)
* Bibliotecas (opcional)
* Eventos (opcional)

Ejemplo:



## Documentación de bibliotecas

Secciones que deben incluirse:

* Nombre de la biblioteca
* Archivo de inclusión requerido
* Descripción general (¿Qué es? ¿Para qué? ¿Por qué?)
* Referencia de las funciones incluidas (Si es conveniente con encabezados de subsección)

Cada función debe documentarse con la siguiente estructura:

* Nombre de la función
* Descripción (¿Qué hace?)
* Prototipo (incluyendo el nombre largo si existe un espacio de nombres)
* Parámetros
* Valor de retorno
* Excepciones
* Ejemplo de uso

### Ejemplo de documentación de biblioteca

```
# dbr.apps

**dbr.apps.dkl**

Ofrece funciones para administrar categorías de accesos directos, accesos directos, tipos de elementos de datos y acciones.

## Administración de categorías

### category.import
Agrega o actualiza los datos de varias categorías de accesos directos

dbr.apps.category.import::&db, &list

#### Parámetros
* db - Es una referencia a la base de datos en uso
* list - Es una lista de objetos que representan a las categorías, cada objeto debe tener dos propiedades: id y title, ambas son cadenas.

#### Valor de retorno
Ninguno (0)

#### Excepciones
Excepciones de bases de datos 

#### Ejemplo

#include "dkli.dkh"
#!
program "Ejemplo"
{
    #include "functions.dkh"
    #include "serialize.dkh"
    #include "dbr.dkh"

    #include "dbr.apps.dkl"

    namespace "dbr.apps"

    ref db=dbr.open("midb@miappgroup")

    ref lista=list.create()

    using categoria
    {
        @"id":"U001"
        @"title": "Categoría de ejemplo 1"
    }

    do list.add(lista,categoria)

    using categoria
    {
        @"id":"U002"
        @"title": "Categoría de ejemplo 2"
    }

    do list.add(lista,categoria)

    do category.import(db,lista)

}

```

Vea <a href="https://docs.induxsoft.net/es/productos/v12/devops/packs/dbext/dbr.apps.md" target="_blank">La documentación de la biblioteca dbr.apps</a> para más detalles.

## Documentación de Tareas
Indicar los siguientes datos de cada tarea:

* Nombre, tipo (en demanda o programada) y propósito de la tarea
* Línea de comandos (si aplica)
* Opciones de configuración

## Documentación de servicios

Datos que deben incluirse por cada servicio:

* Punto final (end point) del servicios
* Descripción general
* Método HTTP de llamada, parámetros y carga útil
* Ejemplo de solicitud HTTP
* Ejemplo de respuesta
* Explicación de los campos de respuesta