La documentación de nuestro software es parte de nuestra conversación entre nosotros: nuestros usuarios, nuestros colegas, nuestra comunidad. De esta manera, mostramos cómo nos valoramos unos a otros, incluido nuestro aprecio. ella.
Conocemos la importancia de esto desde hace algún tiempo, pero es menos fácil expresar estos valores en nuestra práctica.
Una cosa que dificultaba las cosas en Canonical es la complejidad de nuestra cartera de ingeniería, productos y servicios. Nuestro software abarca desde una variedad de herramientas de línea de comando de un solo propósito hasta ecosistemas verticales compuestos por docenas de productos de un solo componente creados por docenas de equipos de desarrollo y productos independientes.
Pudimos crear líneas de productos de software consistentes y coherentes, pero tuvimos menos éxito con la documentación. Queremos hacerlo mejor para nuestros usuarios de documentación; así es como lo haremos.
Un proyecto de transformación de la documentación
Solo sabemos que agradecido La documentación no es suficiente para llevarnos a donde queremos ir. No basta con crear una mejor documentación. Tenemos que crear y mantener de forma consciente y sistemática la documentación del software. Debemos hacerlo de acuerdo con un plan que nos dé la unidad y coherencia que buscamos y que nos seguirá apoyando en el futuro.
Esto es lo que hacemos Estamos en camino un proyecto integral a largo plazo para transformar la documentación. Nuestro objetivo es crear y mantener documentación técnica y prácticas de documentación que sean un estándar excelente en la industria. Queremos que sea lo mejor posible.
Por «mejor» queremos decir Documentación que, sobre todo, comprende, respeta, refleja y atiende las necesidades de sus usuarios. Estos son los valores que defendemos y que expresamos en nuestro trabajo. Son valores por los que queremos ser conocidos.
Este es un compromiso permanente. Es un trabajo que nunca terminará. Ya ha comenzado y se está convirtiendo en parte de la disciplina canónica básica del desarrollo de software. Esperamos que los estándares, la disciplina y los valores que afirmamos de esta manera sean transferidos por Canonical a nuestra comunidad en general y marquen una diferencia para nuestra industria en su conjunto.
Este proyecto cambiará la forma en que casi todos los que trabajan en Canonical piensan, hablan y se acercan a la documentación sobre documentación. Afectará el trabajo de los equipos y las personas en toda la empresa.
Nuestro proyecto de transformación se desarrollará en cuatro áreas de documentación diferentes. Para tener éxito, debemos hacer lo correcto en cada uno de ellos.
Dirección, supervisión, ejecución, equipamiento
Estos cuatro son dirección, cuidado, ejecución y equipo. Estas son cuatro cosas que necesita para tener éxito en cualquier proyecto, no solo en la documentación, sino que también se aplican aquí de manera consistente.
Dirección: con nuestra documentación sabrá a dónde se dirige
dirección representa las exigencias y la calidad de nuestra documentación.
La dirección es hacia donde vamos. No es un objetivo final y fijo porque no hay ninguno. El paisaje en sí cambiará a medida que lleguemos allí. Pero aún necesitamos entender dónde estamos y saber si vamos en la dirección correcta. Necesitamos poder diferenciar entre la documentación que se hizo correctamente y la documentación que no.
El marco de documentación de Diátaxis es nuestro mapa y nuestra brújula para este esfuerzo. Es un sistema ampliamente utilizado que coloca al usuario y sus necesidades en el centro de la documentación.
El marco resuelve algunos problemas clave en la documentación, pero solo será parte de un enfoque más amplio de la documentación que antepone las necesidades del usuario.
Cuidado: nuestra actitud hacia la documentación
cuidado es la actitud y disciplina que aportamos al trabajo de documentación.
El cuidado convierte la voluntad en una acción sostenible y exitosa; es la garantía de que se harán las cosas. No significa que a algunas personas les importe, por muy intensas y apasionadas que sean; debe ser expresado por toda la cultura corporativa e incrustado en su forma de trabajar y pensar.
Transformar una cultura es un trabajo duro y delicado que es demasiado fácil de alterar. Es una tarea de larga crianza que requiere encontrar formas de guiar voluntariamente a los equipos y a las personas con el cambio que desean. Aún así, es más sostenible que intentar hacer las cosas correctas en una cultura hostil. Por el contrario, establecer una buena cultura significa poner en marcha ciclos positivos en los que hacer lo correcto se vuelve fácil y en los que la práctica fortalece los valores.
La documentación, como la ingeniería, es una disciplina. Es menos entendido o discutido que la ingeniería, pero nuestro objetivo es desarrollarlo y formalizarlo como una disciplina, no solo para nuestro propio beneficio, sino para ayudar a avanzar en la documentación del software en general.
Ejecución: así es como hacemos nuestra documentación.
ejecución es la forma en que realmente hacemos lo que hacemos.
El trabajo bien hecho produce mejores cosas y el trabajo en sí es mejor. El trabajo de un artesano experimentado es más eficiente, menos agotador, más suave, más silencioso, menos agotador, más agradable de realizar, más agradable de observar.
La documentación es un oficio, pero ha sido descuidado y sufrido en nuestra industria. Con demasiada frecuencia, las prácticas de autoría y los enfoques de la documentación se basan en aquellos que no se pueden transferir fácilmente. En consecuencia, la experiencia es insatisfactoria para los equipos y las personas: trabajan más duro para obtener peores resultados. Las buenas intenciones rara vez sobreviven a la realidad de las experiencias negativas. Ciertamente, no pueden convertirse en culturas positivas y prósperas si la forma en que las personas trabajan resulta ser un lastre para su progreso.
En Canonical, aplicaremos y desarrollaremos enfoques para evitar estos escollos que reconocen la naturaleza y las necesidades particulares de la documentación y, en particular, el hecho de que la documentación, a diferencia de la tecnología, es Encima algo diferente a sí mismo y persiguiendo un objetivo en constante movimiento.
Nuestro enfoque comienza con la idea de la documentación como actividad, que avanza a través de procesos iterativos y evolutivos, basados en un modelo de crecimiento orgánico bien formado. Nuestro objetivo es llevar la documentación a la práctica. una serie constante de pasos pequeños, simples y de bajo estrés, una actividad común y discreta que encaja bien con nuestro trabajo en software, y produce silenciosamente resultados notables.
Equipo: las herramientas de documentación que utilizamos
equipo es el último de estos cuatro pilares de nuestra búsqueda, las herramientas y máquinas que utilizamos para nuestro trabajo.
Cada uno de los otros representa un valor en sí mismo, pero el equipo es solo un medio para un fin. Es tentador, especialmente en un entorno técnico, dejarse encantar por la tecnología y sus promesas y ser perseguido por sus límites. En realidad, las herramientas, como en cualquier oficio, son en el mejor de los casos un factor habilitador y en el peor un factor limitante. Las herramientas solo existen para servir al trabajo.
Nuestros redactores de documentación, al igual que los artesanos de otras disciplinas, harán su mejor trabajo cuando las herramientas que tienen en sus manos ya no sean un lugar común, por lo que podrán concentrarse en su trabajo en lugar de en las herramientas en sí mismas. El modesto ensayo y error y los modestos informes de experiencias de la vida cotidiana nos guiarán de manera más confiable en nuestras decisiones que las ideas atrevidas y los principios elevados.
Una vez que la cuestión de la tecnología se des-romantiza, es más fácil elegir las herramientas de manera pragmática, sabiendo que es muy poco probable que una elección en particular tome una decisión desde cero y que debemos esperar que la tecnología en sí nunca se quede quieta. reconsiderar nuestras decisiones a su debido tiempo de todos modos. Mientras tanto, estamos revisando nuestras opciones para averiguar dónde y cómo podemos hacer lo correcto para los creadores y usuarios de nuestra documentación. Nuestro trabajo aquí comienza con las preguntas: ¿Qué necesita nuestro trabajo y qué encontramos que le sirva mejor?
Qué significa tener éxito
Nuestro éxito será acertar en los cuatro. La importancia del éxito es reconocida en Canonical: no seremos la empresa de software que queremos ser a menos que podamos lograr la excelencia que buscamos en nuestra documentación.
Creemos que sabemos qué hacer ahora para que nuestras intenciones se conviertan en esfuerzos y nuestros esfuerzos den frutos. Esperamos que, con el tiempo, los frutos de nuestros esfuerzos beneficien a la mayor cantidad posible, no solo a nuestros usuarios y clientes, sino a otras organizaciones de nuestra industria y a las personas a las que sirven.
Si la documentación es realmente parte de cómo nos hablamos, entonces escuchar es parte de eso. Sabremos cuando estemos haciendo las cosas bien porque lo escucharemos. Escucharemos cómo las conversaciones que tenemos cambian a un nivel más profundo de comprensión a medida que avanzamos. Y debemos escuchar constantemente para asegurarnos de que estamos satisfaciendo las necesidades de nuestros usuarios.
Mientras hablamos con usted a través de nuestra documentación, queremos que descubra que estamos abordando estas necesidades con mayor profundidad y confianza. Lo invitamos a juzgar el valor que le damos a la conversación y cómo contribuimos a ella.
