Noticias

Doctor Compasivo | Ubuntu

Las grandes personas que forman Canonical tienen un objetivo: queremos ser la mejor empresa de código abierto del mundo.

Creo que ese también es un objetivo que apoya nuestra gerencia, pero eso no quita el hecho de que todos los que trabajan aquí pueden querer hacer del mundo un lugar mejor a través del software de fuente abierta. Está en nuestra sangre.

Realmente estoy aquí porque quiero escribir una gran documentación. Para ser honesto, los escritores técnicos a veces disfrutan de estándares de excelencia bastante bajos. Estoy muy contento cuando alguien encuentra un pequeño error en un ejemplo de código oscuro cerca de la parte inferior de un artículo extenso; significa que lo está leyendo, que suele ser el criterio principal para el éxito de la documentación. Pero ese no es mi criterio principal.

¿Estoy llamando tu atención?

A medida que crecimos, tuvimos muchos programas dentro de Canonical, lo cual es genial.Dentro del campo doc, tenemos taxi doble Orientación que nos ayuda a organizar nuestro pensamiento y escritura. En el equipo de desarrollo, tenemos todo tipo de componentes de código abierto que no escribimos y que no poseemos, lo cual es valioso porque así es como se hace el código abierto. En nuestra organización de campo y en mi propio trabajo de promoción de desarrolladores, nos conectamos con usuarios y desarrolladores que nos brindan comentarios rápidos, útiles y constructivos.

Ahora, aquí estoy, tratando de reunir un tesoro de orientación mientras construyo documentación que realmente ayude a nuestros lectores. A primera vista, esto puede parecer una tarea, pero en realidad, es un lugar bastante impresionante. Estimado lector, aquí es donde necesito su ayuda.

Como redactor técnico, siempre he sentido que mi principal responsabilidad es Mantiene la atención del lector el tiempo suficiente para enseñarle algo.El arte, por supuesto, se mantiene en el tema. Mi amigo Jack lo expresó de esta manera: «Para explicar realmente cómo hornear un pastel, tienes que inventar el universo». conocimientos relevantes. Quiero que todos obtengan lo que necesitan.

LEER  Computadora de escritorio compacta por $ 529 con Linux en un SoC de brazo octa-core

Definición de «documentación compasiva»

Aquí es donde necesito su ayuda, lectores. Estoy tratando de incorporar los siguientes comentarios sorprendentes en un mejor enfoque de la documentación. Entiende que estoy condensando estos comentarios y agregando mi propia experiencia sensorial sin distorsionar el mensaje central:

  • La documentación no es suficiente, solía serlo, pero se ha vuelto demasiado estéril y cortante.
  • Empaquetamos algunos productos de código abierto y algunos de ellos tienen documentación mala/limitada/incompleta; elegimos ese, por lo que tenemos que asumir cierta responsabilidad por eso.
  • MAAS implica una gran cantidad de aprendizaje periférico (por ejemplo, redes, BMC y empaquetado de imágenes del sistema operativo para su implementación); no hay un solo lugar para aprenderlo todo.
  • Algunos de nuestros usuarios y desarrolladores de MAAS no están completamente preparados para el nivel de conocimiento requerido para hacer que MAAS tenga éxito, sin culpa propia; tal vez heredaron el producto, o tal vez fueron empujados al trabajo porque estaban disponibles, o son las personas con más conocimientos en su organización.

equipo MAAS Este tema fue discutido en un foro abierto el día de hoy. Para nosotros, lo más importante es esta frase, «mejor empresa de código abierto“Ser el mejor significa elegir qué postura cultural de FOSS adoptar y qué postura cultural rechazar.

He estado trabajando en varios proyectos de código abierto desde principios de los 90, a menudo haciendo algún tipo de documentación. A veces me siento incómodo trabajando (o sigo trabajando con) equipos de código abierto debido a algunas actitudes comunes hacia los usuarios finales:

  • «Si los usuarios no entienden la tecnología subyacente, no los necesitamos de todos modos».
  • «Esto no es perfecto. Tienes que resolverlo y Google es tu amigo. Buena suerte».
  • «No soy tu profesor de secundaria».
  • «¿No entiendes? Lo siento mucho por ti».
  • «Aquí está. Si puedes usarlo, genial. Si no, bueno».

El tema aquí se puede resumir como, «El usuario no es mi problema.«. O más específicamente, para mi propia situación, odio la idea de «la comprensión del usuario no es mi problema».

No estoy de acuerdo. Ser la mejor empresa de código abierto del mundo significa empatía por tus usuarios.Escribir la mejor documentación de código abierto significa tener compasión por la comprensión del usuario: comprender nuestra producto; comprensión Nuestro paquete de software libre; y entendimiento El principio básico Requiere la aplicación y el uso exitosos de este producto. Esto es lo que yo llamo «documentación compasiva».

¿Cuáles son nuestras responsabilidades?

Por supuesto, esta idea plantea una cuestión de responsabilidad, especialmente por los productos e ideas de otros. Nos hemos acostumbrado a asumir el papel de emisor de nuestros productos empaquetados, que quedan huérfanos de sus creadores. Esto es desarrollo responsable. Pero surge un problema más espinoso cuando intentamos ser responsables de documentar los productos activos de otras personas, o incluso educar a nuestros usuarios sobre los fundamentos.

Este enigma involucra dos cosas que son muy respetadas en la comunidad de código abierto: propiedad y tecnología actual.

La propiedad significa que debemos tener cuidado de no adelantar al creador original. Si tienen documentación, y esa documentación afecta nuestro producto de alguna manera, es nuestra responsabilidad explicar las cosas claramente. Sin embargo, por respeto, no tenemos ni el derecho ni la responsabilidad de reescribir la documentación de otra persona, especialmente para conveniencia del lector o flujo narrativo.

La tecnología existente esencialmente significa que hay muchas otras personas, todas más inteligentes que nosotros, que han explicado previamente la lógica detrás de nuestra tecnología subyacente. De hecho, la vanguardia es la piedra angular absoluta de FOSS: respetamos su trabajo, le damos crédito y lo respetamos como creador. Extender esto a la escritura técnica significa respetar a los autores anteriores, incluso si sus libros no tienen licencia de código abierto.

Realmente deberíamos guiarlo a través de los recursos existentes y tal vez incluso identificar material relevante específico. Intentar reescribir o resumir material que ha sido explicado (a menudo bellamente) es común en Internet, pero no brinda el debido respeto por los recursos existentes.

solicitar opiniones

Tenemos algunas ideas para plántulas, pero queremos compartirlas con ustedes, queridos lectores, y recibir sus comentarios y sugerencias. Aquí está la esencia:

  • Estamos dispuestos a hacer lo que sea necesario para captar su atención mientras lo ayudamos a comprender lo que necesita saber. No podemos personalizar completamente esta experiencia para cada lector, pero siempre podemos mejorar.
  • Estamos dispuestos a aceptar la responsabilidad por cualquier interpretación técnica relevante que no pueda ser abordada claramente por otras fuentes. Si estamos usando PostgreSQL de una manera específica o única, documentaremos todo lo que pueda ser confuso o poco claro con solo leer la documentación de PostgreSQL.
  • Asumimos la responsabilidad de cualquier documentación exclusiva de nuestros productos y nos esforzamos por garantizar que esté enfocada, completa y sea fácil de entender.
  • Queremos usar la idea de documentos estructurados con moderación, p. taxi dobleformato de página y herramientas de navegación, y modere su uso de una manera que permita una narración fluida mientras reduce la necesidad de cambiar el contexto cuando intenta aprender o lograr algo.
  • Asumimos la responsabilidad de ayudarlo a utilizar la documentación del propietario y la tecnología existente de manera más efectiva para mejorar su conocimiento y comprensión en disciplinas directamente relacionadas con MAAS.
  • queremos hacer todos De una manera que ofrezca el debido respeto a quienes han estado allí, ese es el espíritu de FOSS.

Queremos sus comentarios. Hemos pensado un poco en esto, pero en última instancia, el objetivo es poder escribir documentos que capten su atención adecuadamente y le brinden la información que necesita de la manera más adecuada.

Por favor dinos tu opinión. Realmente queremos saber.

LEER  # 138 Hardware Slimbook One AMD

Publicaciones relacionadas

Deja una respuesta

Tu dirección de correo electrónico no será publicada. Los campos obligatorios están marcados con *

Botón volver arriba