La importancia de preparar buenos documentos en los proyectos

Me gustó leer Documents: The architect’s programming language. No es que yo tenga que ver con ese mundo, pero me veo con frecuencia leyendo documentos generados por otros (estudiantes, fundamentalmente) y, en algunos casos, ayudándoles a mejorarlos.

Nos habla de los arquitectos de sistemas y su papel en la gestión del trabajo de otros, mediante su conocimiento de como organizar ideas y convertirlas en proyectos.

I mean that an architect knows effective, repeatable processes for organizing and deploying ideas, above and beyond the processes that organize and deploy machines and applications. They know there are limits to what you can achieve with a code push; the most important issues require input, collaboration, and consensus from people with different perspectives and job titles.

Para ello necesitan conocer no sólo la parte técnica y de desarrollo, sino también documentar, escribir las propuestas, organizar esa información …

There are several tools, actually: Confluence, Google Docs, Notion, XWiki, BookStack…you get the idea. If you can write bullet points and link between documents, you can deploy ideas. The most effective way to get something done in most organizations is to write a document, share it with the people most likely to care, and listen to their feedback.

Luego entra en el detalle de sus recomendaciones para preparar un buen documento, con listas (bullet points), cabeceras, y otros recursos que permiten recorrer el documento de acuerdo a las necesidades del lector.

The main thing you want to avoid is a giant wall of text. Often the people whose attention your document needs most are the people with the most demands on their time. If you send them a four-page essay, there’s a good chance they’ll never have the time to get through it. A well-organized set of bullet points, on the other hand, makes it possible for them to scroll through, glean the information they need, and respond whenever they have a minute to spare.

Luego, la revisión por otros: puede que el documento nos parezca magnífico, pero a la vez es posible que tenga defectos.

Once you’ve got all the necessary information written down, consider doing a sanity check. Send it to someone you work closely with and ask them to point out anything that seems wrong or doesn’t make sense. Then use their feedback to clarify, reorganize, or rephrase.

Finalmente, da algunas ideas más de cómo organizar la información, qué debería contener y otras ideas.