Esta guía proporciona instrucciones sobre cómo escribir documentación efectiva de tipo “cómo hacerlo” para Discourse. Cubre elementos esenciales como la estructura y el estilo, la consideración del público objetivo y el mantenimiento.
Nivel de usuario requerido: Cualquiera puede escribir nuevas guías de “cómo hacerlo”
Escribir documentación efectiva de tipo “cómo hacerlo” es crucial para ayudar a usuarios, moderadores, administradores y administradores de sistemas a realizar diversas tareas dentro de Discourse. Esta guía le ayudará a crear guías de “cómo hacerlo” claras y valiosas para la comunidad.
Resumen
En esta documentación, aprenderá:
- Por qué es importante escribir un “cómo hacerlo”
- Qué información debe incluirse
- Directrices para la estructura y el estilo
- Dónde publicar estos temas
- Cómo mantenerlos después de publicarlos
¿Por qué escribir un “cómo hacerlo”?
¿Alguna vez ha necesitado realizar una tarea y no pudo recordar cómo hacerlo? Escribir un documento de “cómo hacerlo” es una excelente manera de documentar procesos en Discourse. Si está teniendo dificultades con un proceso en particular, es probable que otra persona también lo esté. Documentarlo ayuda a todos.
Obtenga más información sobre lo que hace que un “cómo hacerlo” sea diferente de otros tipos de documentación, como tutoriales o guías de referencia, en esta guía de Divio.
Escribir o revisar un “cómo hacerlo” es una excelente manera de comenzar a contribuir con su conocimiento de Discourse a la comunidad. Para otras formas de contribuir, consulte la guía sobre cómo contribuir a Discourse.
¿Qué información debe incluirse?
Un “cómo hacerlo” debe ser una guía paso a paso que guíe al usuario hacia un resultado específico. Por ejemplo, un “cómo hacerlo” titulado “Configuración de HTTPS para Discourse” debe proporcionar instrucciones para configurar HTTPS.
Puntos clave a recordar al escribir una guía de “cómo hacerlo”:
- Manténgase en el tema y sea claro
- Evite la información innecesaria
- Sea conciso pero informativo
- Explique por qué es beneficioso lograr el resultado final
Considere a su audiencia
Hay diferentes audiencias para los “cómo hacerlo” de Discourse, cada una requiere un nivel de explicación diferente. Utilice las categorías de documentación como guía para saber a quién dirigir su guía:
- Documentation > Using Discourse
- Documentation > Site Management
- Documentation > Integrations
- Documentation > Hosted Customers
- Documentation > Self-Hosting
- Documentation > Migrating to Discourse
- Documentation > Developer Guides
- Documentation > Contributing
Comprenda el nivel de habilidad técnica de su audiencia y adapte su guía en consecuencia. Algunos consejos:
- Evite pasos que la audiencia no pueda realizar (por ejemplo, los clientes alojados generalmente no tienen acceso a comandos de consola)
- Mantenga las instrucciones claras y evite un lenguaje altamente técnico para usuarios no técnicos
- No agregue información de fondo que su audiencia ya deba conocer
Estructura y estilo
La guía de estilo de documentación cubre todo lo que necesita saber sobre cómo estructurar y dar estilo a las guías de “cómo hacerlo” (y a toda la documentación de Discourse):
Publicar una guía
Publique las guías en una subcategoría de la categoría padre Documentation y etiquételas con how-to. Todas las guías requieren la aprobación del equipo de Discourse, que se gestionará automáticamente a través del proceso de moderación. La guía de estilo describe cada categoría con más detalle para ayudarle a decidir dónde debe publicarse su guía.
Mantener su guía
Una vez que haya publicado un “cómo hacerlo”, manténgalo actualizado. Así es como puede ayudar a mantenerlo:
- Esté atento a las respuestas — Integre los comentarios de la comunidad en la guía.
- Pruebe la guía usted mismo — Revise la guía periódicamente para asegurar que sigue siendo precisa.
- Edite información faltante o incorrecta — Si tiene un Nivel de Confianza 2 o superior, edite la primera publicación del “cómo hacerlo”.
- Marque temas para obtener asistencia — Si no puede realizar una edición, marque la publicación con “Otra cosa” y explique lo que se necesita.
En la mayoría de los casos, los comentarios en las guías oficiales de “cómo hacerlo” se eliminarán después de un mes para mantener el enfoque en la guía en sí.
¡Gracias por mejorar la documentación de la comunidad de Discourse! Si está atascado, no dude en pedir ayuda. La mejor manera de comenzar es contribuyendo y aprendiendo sobre la marcha.