Guía de estilo

Empezando

Antes de comenzar su proceso de escritura, aquí hay algunas cosas que debe considerar:

1. Determinar el propósito y el uso

   Establecer el propósito de su artículo debe ser el primer paso de su proceso de escritura. Determina lo que quieres que los lectores sepan cuando terminen de leer. Definir los objetivos lo ayudará con cada paso posterior en la escritura.

2. Identificar la audiencia y su necesidad

   Tenga en cuenta que la documentación será leída principalmente por desarrolladores e integradores de sistemas curiosos o contribuyentes, que debemos suponer que tienen al menos un nivel elemental de conocimiento técnico. Determine qué información y cuánto detalle necesitan los lectores para lograr el propósito de su artículo.

3. Organiza la información

   Una vez que haya determinado qué información necesitan los lectores, organice la información de manera lógica para lograr el mejor flujo y comprensión.

¡Ya estás listo para comenzar a escribir! Visite esta página para saber cómo descargar el proyecto y enviar la documentación.

Herramientas

Esfinge: |esfinge| es el generador de documentación que usamos para facilitar la redacción de documentación. Sus características (extensas referencias cruzadas, estructura jerárquica, índices automáticos, etc.) y gama de idiomas lo convierten en una herramienta útil para nuestros propósitos.

textoreestructurado: Sphinx usa reStructuredText como su sintaxis de marcado. reStructuredText es un sistema sencillo pero potente esa es una de las principales fortalezas del uso de Sphinx. Puedes referirte a la reStructuredText |primera hoja de trucos| para lo básico.

GitHub: GitHub es el servicio de hospedaje que usamos para nuestros documentación. Para comprometer sus contribuciones, necesitará estar familiarizado con la plataforma. Los principiantes pueden empezar a aprender leyendo esto |gh-introducción| a Git.

Transifex: Transifex es la plataforma de localización colaborativa que utilizar para traducir nuestra documentación a varios idiomas. Sigue nuestro guide para empezar a contribuir con las traducciones.

patrones de escritura

Si bien no es razonable esperar que todos los muchos escritores en el equipo de redacción técnica tenga un estilo de redacción idéntico, podemos intentar tener una voz consistente que resuene con los lectores al manteniendo un patrón de escritura similar. Tenga en cuenta estas reglas básicas como usted escribe.