Propósito
The Categorías de guías prácticasson el lugar adecuado para documentar tareas más complejas. Estos son para cosas que involucran varios módulos diferentes o que necesitan describir conceptos y entrar en muchos detalles.
Una guía práctica es ideal para cosas como:
- Cómo ejecutar Tryton con Docker(qué pasos se requieren, qué comandos deben ejecutarse y qué hace cada uno)
- Cómo importar stock inicial (cómo crear productos, establecer precios de costo adecuados y crear el envío interno inicial desde la ubicación del proveedor)
- Cómo organizar las ubicaciones del almacén (incluyendo qué estrategias se pueden utilizar, cuáles son sus ventajas y desventajas, qué problemas de rendimiento existen y qué se puede hacer para evitarlos)
Cada procedimiento debe centrarse en un solo tema; siempre se pueden incluir enlaces a temas relacionados u otra documentación cuando sea necesario. Es mucho mejor agregar documentación en el lugar correcto y luego vincularla para evitar duplicar documentación.
Estilo general
Consistencia
Intente ser coherente con la forma en que se han escrito otros procedimientos. Lea algunos de los procedimientos existentes para tener una idea de su estilo y cómo se han estructurado. Esto hará que todos los procedimientos resulten familiares para los lectores y les ayudará a aprovecharlos al máximo.
Audiencia
Al escribir su manual, intente recordar a qué audiencia está destinado el documento. Hay subcategorías separadas para diferentes audiencias, así que intenta enviar tu tutorial al lugar correcto.
Formato
El editor le permite formatear el procedimiento según sea necesario. Tiene botones que pueden poner el texto en negrita o cursiva y le permite insertar cosas como enlaces, viñetas y listas numeradas. Utilícelos según corresponda.
Es posible que desee escribir su procedimiento sin conexión y luego copiarlo y pegarlo cuando esté listo para enviarlo. Si haces esto, puedes usar el editor para ver cómo se representan los diferentes estilos en texto sin formato.
Secciones
Lo ideal sería que el procedimiento estuviera estructurado de forma lógica, con sus partes divididas en secciones y subsecciones apropiadas.
Las secciones se introducen con un título de sección que usa uno o más#símbolos al inicio de la línea. el número de#Los símbolos indican el nivel de la sección.
Por ejemplo:
# Main Section
## Subsection
## Subsection
### Subsubsection
# Next SectionTabla de contenidos
A menudo es una buena idea agregar una tabla de contenido al tutorial. Esto se generará automáticamente a partir de las secciones del tutorial si incluyes, en la primera línea:
<div data-theme-toc="true"></div>