Se distribuyen cuatro tipos de documentaci贸n en dos ejes: pr谩ctica-teor铆a y formaci贸n-trabajo.
Recientemente salieron dos publicaciones sensacionales:
Y muchos preguntaron: "Alguien, por favor, ens茅帽eme a redactar una buena documentaci贸n".
No pretendo ser un experto, pero creo que soy bueno en eso.
He bebido bastante caf茅 y tratar茅 de explicar lo que s茅.
TL; DR: redacta documentaci贸n para resolver un problema espec铆fico para un grupo espec铆fico de personas, no solo para tener la documentaci贸n.
Escribe bien
Primero, debes ser bueno escribiendo. El autor de Drunken Revelations ha negado claramente esta afirmaci贸n, pero para la mayor铆a puede que no funcione. Tienes que poder tomar temas y encontrar el punto principal, mostrar los detalles clave. Estos detalles deben secuenciarse correctamente y luego traducirse en oraciones claras.
La buena redacci贸n no se trata solo de documentaci贸n, por supuesto. Puede poner a prueba su capacidad en esta 谩rea con cualquier tipo de escritura. 驴Puedes escribir c贸mo encontrar algo en tu casa? 驴Puedes escribir un breve discurso? Si necesita trabajar en esta 谩rea, le sugiero que practique escribiendo algo m谩s que documentaci贸n. Escribe publicaciones de blog, escribe historias cortas, escribe cartas a amigos, lo que sea. Si no lee libros con regularidad, comience ahora. Su cerebro necesita estar entrenado en una gran cantidad de texto bien escrito antes de que pueda saber qu茅 funciona y qu茅 no en su caso particular. Desarrollar una habilidad de edici贸n que sea muy diferente a una habilidad de escritura (la escritura se vuelve m谩s f谩cil,si conf铆a en sus habilidades de edici贸n, no se filtrar谩 tanto).
El consejo m谩s 煤til para escribir documentaci贸n es escribir en un estilo conversacional. Es mucho m谩s f谩cil percibir la informaci贸n de un texto informal.
Tipos de documentaci贸n
Bien, ahora volvamos a la documentaci贸n.
Hay diferentes tipos de documentaci贸n, y las personas se inventan cuerdas, tratando de obtener un tipo de documentaci贸n para hacer el trabajo de otro. El estiramiento tiene dos ejes:
- Informaci贸n para la formaci贸n VS informaci贸n para el trabajo.
- Pasos pr谩cticos VS informaci贸n te贸rica.
(Este no es mi pensamiento, lo vi en https://documentation.divio.com/ )
La informaci贸n de formaci贸n que contiene pasos pr谩cticos se denomina tutorial. Si no contiene ning煤n paso pr谩ctico, esta es una explicaci贸n. Ambos tienden a ser m谩s adecuados para principiantes, por lo que deben centrarse en explicar conceptos y t茅rminos (e informaci贸n de fondo). En cuanto a las explicaciones, es muy 煤til tener un breve resumen en la parte superior.
Es seguro asumir que, gracias a la informaci贸n sobre cu谩ndo est谩 trabajando, alguien ya tiene una idea general de lo que est谩 sucediendo.
La informaci贸n te贸rica utilizada en el trabajo se denomina referencia. Esto incluye documentaci贸n para cada m茅todo. La documentaci贸n de ayuda es un lugar completamente in煤til para albergar un tutorial.
Si esto no es teor铆a, entonces esta gu铆a. La gu铆a es b谩sicamente similar a un tutorial, con dos diferencias importantes: asume cierta familiaridad con el tema y el objetivo es realizar una tarea espec铆fica, no ense帽ar. La lista de verificaci贸n es una gu铆a r谩pida, pero a煤n puede ser 煤til si es muy f谩cil olvidarse de un paso importante. Utilice las gu铆as cuando haya pasos que deba repetir. Son especialmente valiosos cuando la persona que realiza los pasos no sabe c贸mo completar la tarea (ya sea alguien del otro equipo o usted en un a帽o).
Elija el tipo de documentaci贸n a escribir seg煤n las necesidades de su lector. Puede ser que su c贸digo sea bastante autodocumentado, y leer la firma del m茅todo realmente le diga lo que est谩 haciendo el m茅todo. Excelente. Esto es para documentaci贸n de referencia. Ahora escribe los otros tres tipos.
Si todo lo que tiene es documentaci贸n de referencia, la informaci贸n ser谩 un mont贸n in煤til de hechos aleatorios para los lectores que no est茅n familiarizados con los conceptos b谩sicos. La documentaci贸n de ayuda es como tener una descripci贸n detallada de las intersecciones cuando los nuevos lectores buscan mapas de carreteras.
Creo que en realidad hay un quinto tipo de documentaci贸n: migas de pan. Estos son peque帽os comentarios en c贸digo o notas en documentos (o incluso mensajes de error en linters personalizados) que se帽alan a los lectores lo que necesitan saber. Puede escribir un peque帽o comentario con un enlace al ticket de Jira explicando por qu茅 se necesita este c贸digo, o puede decirle a la gente qu茅 comando ejecutar para corregir el error. Las migas de pan son realmente f谩ciles de agregar a los documentos y ahorran mucho tiempo.
Por qu茅
Es muy f谩cil olvidarse de escribir sobre cosas que parecen obvias. Por supuesto, c贸mo creamos un microservicio, no necesito escribir por qu茅 estamos haciendo esto. Pero es necesario.
Esto es obvio para usted, pero no para el lector. El razonamiento detr谩s de las decisiones nos parece realmente obvio porque hemos pasado mucho tiempo pensando en ello.
Cuando explica por qu茅 est谩 haciendo algo, se ve obligado a rastrear mentalmente los pasos que llevaron a la decisi贸n. Resulta que tambi茅n es una excelente manera de presentarle ciertos temas.
Si est谩s atascado tratando de explicar por qu茅, imagina c贸mo ser铆a el mundo si lo que est谩s documentando desapareciera de repente. 驴A qui茅n le importa lo que ven?
Es incluso mejor si puede explicar la raz贸n con una historia. La gente es muy buena procesando y recordando historias.
Me gustan los otros comentarios en la documentaci贸n. Por ejemplo. "Sabemos que no es bueno, y realmente queremos que funcione como X, pero requerir谩 que el equipo de T actualice sus materiales, y est谩n muy abrumados, as铆 que vivimos con eso por ahora". Es el tipo de informaci贸n que re煤ne todo en la cabeza de las personas y les hace sentir que comprenden lo que est谩 sucediendo.
Temas no t茅cnicos
El hecho de que est茅 documentando un tema t茅cnico no significa que el lector tampoco necesite saber algunas cosas no t茅cnicas. La raz贸n por la que este es el caso es muy grave.
Otros detalles no t茅cnicos 煤tiles que incluyen:
- , (, -, , ).
- . 芦 X , Y, Z禄
- . 芦 , , , 禄.
- , 芦 , ...禄
Los tutoriales est谩n destinados a familiarizar a las personas con el tema. Esta es una muy buena manera de hacerlo porque las personas aprenden mejor cuando hacen algo, en lugar de simplemente leer.
Los tutoriales tambi茅n requieren una gran inversi贸n (en comparaci贸n con otros tipos de documentos). Escribirlos probablemente solo tenga sentido si muchas personas necesitan aprender un tema. Si son solo unas pocas personas, reunirse con ellas cara a cara (o de c谩mara web a c谩mara web) es probablemente la mejor manera de aprovechar el tiempo.
La trampa al escribir tutoriales es intentar explicarlo todo. Resista la tentaci贸n de enumerar todos los detalles t茅cnicos y todas las excepciones a las reglas establecidas. Solo desea que sus lectores comprendan la mec谩nica b谩sica. Se pueden dejar peque帽os detalles para la documentaci贸n de personas m谩s experimentadas.
Tambi茅n muy a menudo los tutoriales simplemente no funcionan cuando alguien intenta trabajar con ellos. Debe probar los pasos que escribi贸 (idealmente en una computadora nueva sin todos los componentes ya instalados) para asegurarse de que est茅n completos y realmente funcionen. Luego, siga los pasos la pr贸xima vez que alguien necesite usar esta gu铆a y vea d贸nde se atascan.
Los pasos tambi茅n estar谩n desactualizados, as铆 que aseg煤rese de escuchar a las personas que tienen problemas con ellos.
Gu铆as
Las gu铆as tienden a ofrecer un buen retorno de la inversi贸n. Dedicar 10 minutos a enumerar los pasos en una lista con vi帽etas puede ahorrarle una hora para pensar qu茅 hacer a continuaci贸n.
Esto es especialmente valioso cuando es dif铆cil comprender cu谩les son estos pasos, o si es f谩cil omitir un paso importante.
Escriba gu铆as cuando acabe de pasar por el proceso y est茅 motivado para evitar volver a averiguarlo todo.
Explicaci贸n y ayuda
Para ser honesto, no estoy seguro del valor de la documentaci贸n de referencia de estilo javadoc. Por supuesto, si un mill贸n de personas van a utilizar su lecci贸n, arremangarse y documentar todo hasta el m谩s m铆nimo detalle. Pero si solo est谩 leyendo su equipo, ya sabr谩n el 99% de lo que puede escribir.
Las explicaciones son generalmente m谩s 煤tiles, especialmente cuando se enfocan en explicar las razones. Si explica al usuario y las limitaciones t茅cnicas que conducen a la creaci贸n de un dise帽o, casi puede olvidarse de explicar el dise帽o en s铆; armado con informaci贸n de fondo, alguien puede resolverlo por su cuenta leyendo el c贸digo. Puede (eventualmente) aprender la estructura simplemente leyendo el c贸digo, pero es dif铆cil o incluso imposible entender las razones de esta manera.
Pr谩ctica de la documentaci贸n
Escribir documentaci贸n lleva tiempo. Un mont贸n de tiempo. Dedicar este tiempo a la documentaci贸n no es simplemente m谩gico porque alguien dice "necesitamos m谩s documentaci贸n". Debe reservar tiempo para esto y pasar horas escribiendo. No, esta no es la forma m谩s divertida de pasar la noche del jueves, pero tienes que hacerlo.
驴O no? Solo debe escribir documentaci贸n cuando sea 煤til. No escribir铆as c贸digo solo para escribir m谩s c贸digo (o tal vez lo har铆as, pero yo no). Escribe c贸digo para resolver un problema espec铆fico. Tambi茅n debe escribir documentaci贸n para resolver un problema espec铆fico.
Este "algo" se puede implementar para ayudar a nuevas personas a dinamizar el equipo, reducir el factor bus en el equipo, evitar errores debido a que se olvidan los pasos, ahorrar tiempo a las personas al realizar acciones, proporcionar contexto, construir acuerdos, escribir grosero pero importante detalles, etc. Si no sabe por qu茅 est谩 escribiendo documentaci贸n, no lo haga. Una vez que sepa por qu茅, seleccione la documentaci贸n adecuada para el problema que se est谩 resolviendo.
Por favor, en nombre de todo lo sagrado, no escriba documentaci贸n como esta:
/**
* @param customer The customer
* @param order The order
* @return The price
*/
public Price getPrice(Customer customer, Order order) {}
Esto no tiene sentido y ense帽a a los lectores a omitir mentalmente los comentarios. Omitir谩n comentarios que realmente contengan algo 煤til. Si no tiene nada que decir, no lo diga.
La documentaci贸n, como el c贸digo, debe mantenerse. Tienes que pagar por su almacenamiento. Debes tomarte el tiempo para apoyarlo. Afortunadamente, esto suele ser mucho m谩s econ贸mico que mantener el c贸digo. Unas pocas horas al mes es todo lo que necesita para leer la wiki completa y corregir lo que est谩 mal ahora mismo.
Sugerencia: cree una secci贸n de "archivo" en su documentaci贸n y mueva los materiales obsoletos all铆. Conserva el contexto hist贸rico, es mejor que simplemente borrar la documentaci贸n y no necesita ser enga帽ado por lectores desprevenidos.
Una forma de ahorrar tiempo es convertir otros trabajos en documentaci贸n. Si necesitas explicarle a un colega c贸mo integrarte con tu sistema, copia lo que escribes en Slack en un documento. Si escribi贸 la documentaci贸n del proyecto, copie varias secciones en la documentaci贸n y dedique 10 minutos a prepararla. Siempre que necesite explicar algo a un revisor en una revisi贸n de c贸digo, expl铆quelo con un comentario en el c贸digo, no una confirmaci贸n en Github. 驴Su boleto de Jira explica por qu茅 debe completarse la tarea? Genial, copia esto y ya tienes la documentaci贸n. (Si no es as铆, 隆pida al interlocutor que lo escriba!)
D铆gale a la gente ad贸nde ir para hacer preguntas. Para escribir "si tiene alguna pregunta, puede contactarnos en # team-channel en Slack" en unos 15 segundos. Esto puede ahorrarle horas si se confunde. En mi opini贸n
, bastante buena recuperaci贸n. Entonces, el caf茅 se est谩 acabando, as铆 que me detendr茅 all铆.