Escribir documentación efectiva para Discourse

Hola Simon! :blob_wave:

Iba a ver cómo resultaba esto, pero sí, yo también intento evitar las contracciones.

Jajaja, sí… No voy a usar ninguna de esas palabras en los documentos, no sea que revele mi :face_with_monocle:.

Definitivamente: Example Domains

¡Este es el punto que vine a discutir! :smiley:

Hemos tenido muchas idas y venidas sobre esto, y me alegró ver que se incluyera en la guía de estilo por defecto.

Aquí explico por qué creo que es importante: producir documentación debe ser accesible para tantos miembros de nuestra comunidad como sea posible, incluidos (¿especialmente?) nuestros miembros del equipo de Discourse.

Discourse es un software de discusión social. Y parte de la documentación es realmente una conversación continua. Si estoy compartiendo una práctica sobre cómo incorporo miembros a mi comunidad, querría que se me presentara como el “propietario” de ese tema, para poder responder preguntas y ampliar el tema.

Por otro lado, si un cliente pregunta sobre una característica que nunca llegamos a explicar, me gustaría poder usar la guía de estilo y producir documentación útil y general, lo que siento que ser el propietario del tema presenta más inercia para publicar.

Además, si producimos documentación fuera de Discourse (una integración o producción a partir de comentarios de código o lo que sea), tener un “usuario de documentación” es probablemente más fácil como detalle de implementación. :thinking:

No creo que esta guía impida que la gente inyecte su voz y personalidad, y organice la discusión. ¡Pero sería genial si ayudara a más personas a practicar la documentación, que de otro modo no lo harían (¡y luego podemos animarlos a ser más personales!) :smiley:

3 Me gusta