# Composición de la documentación La documentación está principalmente dividida en dos grupos de contenido dirigidos a: Especialistas en TI (DevOps) y Usuarios finales. La raíz de la documentación de V12 es: ```/es/productos/v12``` ## DevOps La documentación para DevOps está en ```/es/productos/v12/devops/``` en donde se encuentran algunos archivos de contenido aplicables a toda la plataforma y la carpeta 'packs' con carpetas con el id de cada paquete con los detalles técnicos de cada uno. Para detalles acerca de la estructura y contenido de la documentación técnica, vea: [Forma y estilo](forma-estilo-doc.md) Los guiones de pruebas deben documentarse en un único archivo denominado test.md en la ubicación que corresponda según lo siguiente (y su id de paquete): ``` https://docs.induxsoft.net/es/productos/v12/devops/packs/{id_del_paquete}/test.md ``` Con la siguiente estructura: ``` # Nombre del paquete ## Nombre de la aplicación ### Caso de prueba N #### Descripción #### Acciones #### Consideraciones #### Resultados ``` ## Users La documentación de usuario se genera semi-automáticamente con la información del proyecto V12 en la base de datos de Induxsoft. Por lo tanto, automáticamente se generan: * Página del paquete: ```/es/productos/v12/users/{id_del_paquete}/``` * Página de aplicación: ```/es/productos/v12/users/{id_del_paquete}/{id_aplicación}/``` * Página de vista: ```/es/productos/v12/users/{id_del_paquete}/{id_aplicación}/?view={id_de_la_vista}``` * Página de acción: ```/es/productos/v12/users/--actions/{id_de_acción}/``` Las páginas generadas automáticamente pueden incluir contenido escrito manualmente que debe estar ubicado dentro de la carpeta del sistema 'pieces' en ```/web/docs.induxsoft.net/es/productos/v12/pieces/``` Cada paquete debe tener su propia carpeta dentro de 'pieces', por ejemplo: pregop tiene la carpeta 'pieces/pregop' y alibeb 'pieces/alibeb' Para incluir contenido en la página del paquete, debe existir un archivo con extensión .dk, .dkl, .html o md en la carpeta del paquete con el mismo nombre del paquete. Ejemplo: El archivo ```/web/docs.induxsoft.net/es/productos/v12/pieces/pregop/pregop.dkl``` se incluye en la página principal del paquete. Para incluir contenido en la página de la aplicación, debe existir un archivo con extensión .dk, .dkl, .html o .md en la carpeta del paquete con el mismo nombre del paquete y el id de la aplicación delimitados por un caracter '.'. Ejemplo: El archivo ```/web/docs.induxsoft.net/es/productos/v12/pieces/alibeb/alibeb.recetas.html``` se incluye en la página principal de la aplicación recetas de alibeb Para incluir contenido en la página de una vista: El archivo ```/web/docs.induxsoft.net/es/productos/v12/pieces/alibeb/alibeb.recetas.list.html``` se incluye en la página de la vista 'list' de la aplicación de recetas de alibeb. Para incluir contenido en la página de una vista que corresponde a un estado de la vista: El archivo ```/web/docs.induxsoft.net/es/productos/v12/pieces/alibeb/alibeb.recetas.form.new.html``` se incluye en la página de la vista 'form', en la sección del estado de la vista 'new' de la aplicación de recetas de alibeb. Por su parte, las acciones deben estar en la carpeta ```/web/docs.induxsoft.net/es/productos/v12/pieces/_actions``` y el nombre del archivo debe ser el id de la acción. ### Contenido de las páginas de documentación para el usuario #### Página del paquete * (Contenido generado automáticamente) * Conceptos, explicaciones generales y enlaces a otras páginas que complementen el por qué de las cosas #### Página de aplicación * (Contenido generado automáticamente) * Conceptos, explicaciones generales y enlaces a otras páginas que complementen el por qué de las cosas y el flujo de datos * Cómo acceder a la aplicación Consideraciones: Para explicar cómo acceder a la aplicación, use una plantilla como la siguiente: ``` Use el botón 'Acciones rápidas' de la barra de navegación de la interfaz de V12 para introducir el código 'código' o bien, desde la página de inicio haga click en el icono: [ICONO] ``` #### Página de vista * (Contenido generado automáticamente) * Explicaciones y enlaces a contenido relevante cuando sea útil * Campos o columnas de la vista, indicando para qué sirven, el tipo de datos que admiten y lo que significan * Imagen (screenshot) de la vista #### Contenido de estado de la vista * (Contenido generado automáticamente) * Explicaciones y enlaces a contenido relevante cuando sea útil * Campos o columnas de la vista, indicando para qué sirven, el tipo de datos que admiten y lo que significan * Imagen (screenshot) de la vista #### Página de acción * (Contenido generado automáticamente) * Propósito, explicaciones y enlaces a contenido relevante cuando sea útil * Requisitos previos para la realización * Guía de pasos a seguir para realizar la acción * Excepciones (errores) previstas Consideraciones: Tomando en cuenta que las acciones pueden ser independientes o dependientes del contexto, la plantilla de pasos deberá iniciar de manera similar a: ``` Acciones independientes del contexto 1. Use el botón 'Acciones rápidas' de la barra de navegación de la interfaz de V12 para introducir el código 'código' o diríjase a la aplicación 'XXXXX' y presione el botón 'XXXX' Acciones dependientes del contexto 1. Acceda a la aplicación 'XXXX' 2. Seleccione ... ``` ## Otras carpetas previstas Use las siguientes carpetas para propóstios específicos: * ```/web/docs.induxsoft.net/es/productos/v12/posts/``` Artículos en general de la documentación * ```/web/docs.induxsoft.net/es/productos/v12/img/``` Imágenes en general de la documentación ## Desplegar la documentación en otros sitios Existirá la necesidad de proporcionar documentación personalizada que esté mayormente basada en la documentación oficial de V12, para lo cual se preven las siguientes estrategias: * El archivo dochelper.dk que está en ```web/docs.induxsoft.net/_private/v12/``` deberá servir de base para un nuevo paquete de v12 que incluya una plantilla de sitio Web, al tiempo que en su renderizador se incorpore el reemplazo de la cadena del host y la ruta de base de la documentación de v12 para poder usar el contenido existente solamente "transplantándolo" y sin necesidad de realizar cambios. Por ejemplo: ``` html=replace(replace(html'docs.induxsoft.net','el host del usuario'),'es/productos/v12','la ruta de base de la documentación en el host del usuario') ``` * Trasladas los elementos del proyecto de 'epifania' a la base de datos del usuario (como se hizo en sigesac.sipbsa) para que además existan los elementos específicos del cliente. * Ajustar las variables de configuración de dochelper.dkl según corresponda a las necesidades del sitio de documentación del cliente El objetivo es que la documentación de V12 no se modifique en el despliegue del cliente, solo complemente la que corresponda a los paquetes que se le hayan desarrollado.