Esta página contiene los detalles de un proyecto de redacción técnica aceptado para la temporada de Documentos de Google.
Resumen del proyecto
- Organización de código abierto:
- TheGoodDocsProject
- Escritor técnico:
- Locuidad
- Nombre del proyecto:
- Guía de arquitectura de la información
- Duración del proyecto:
- Duración estándar (3 meses)
Project description
Plan de la guía de arquitectura de la información
Este documento abarca la planificación de una guía de arquitectura de la información para el buen proyecto de Documentos. Esta se preparó como parte de un envío de la temporada de Documentos de Google 2020. Describe el caso de uso para la guía propuesta y esboza un plan de la estructura de dicha guía para fines de planificación.
La arquitectura de la información (IA) se refiere a cómo se organiza el contenido. Abarca la estructura del contenido sin definir el estilo o las palabras usadas dentro de él. Por ejemplo, un plan de IA consideraría quién es el lector, cómo aborda el contenido y el entorno en el que está leyendo. Luego, considera una estructura adecuada para el contenido que cumpliría mejor con estos requisitos de lector.
En un mundo perfecto, la documentación se diseña comenzando con una estrategia de contenido que utiliza objetivos comerciales para definir los objetivos de la documentación. Luego, se usa la estrategia de contenido para crear una AI, que define el diseño y la estructura de la documentación. Desde allí, se pueden elegir cadenas de herramientas y escribir contenido. La realidad en la mayoría de los proyectos de código abierto es que la estrategia de contenido es tan simple como "escribir documentación para que las personas sepan cómo utilizar este proyecto", pero incluso esa simple estrategia es suficiente para poder definir una IA eficaz.
El objetivo de esta guía es proporcionar una herramienta simplificada a los escritores no profesionales para que desarrollen una IA que sea suficiente para determinar qué plantillas deben usar. Debe ser lo suficientemente simple para que lo complete un ser humano común en una tarde, y debe priorizar la acción por sobre la educación. Lo ideal es que presente conceptos de manera concisa, guíe al lector a considerar esos conceptos en relación con su propio proyecto y use el resultado de eso para pasar al siguiente concepto.
Como andamiaje para este proyecto, se requieren algunas actualizaciones del archivo README del proyecto, de modo que los lectores entiendan cómo comenzar con el buen proyecto de Documentos y puedan usar la guía de IA de manera eficaz para guiar sus opciones de plantillas.
Público principal
Todas las personas que quieran usar las plantillas de The Good Docs Project para crear documentación para su proyecto
Casos de uso: Esta sección está diseñada para explorar cómo los lectores abordan la Guía de IA. Esto puede ayudarnos a identificar cómo debe estructurarse la guía para ofrecer el mejor servicio a esos lectores.
Situación: Una persona está trabajando en un proyecto de código abierto con poca o ninguna documentación, o en un paquete de documentación mal organizado o escrito. Deciden usar The Good Docs Project para organizar su documentación, pero no saben por dónde empezar. Sigue el archivo README para comprender cómo comenzar a usar las plantillas y el Information Architecture Guide para desarrollar su estrategia de contenido y planificar cómo se verá su paquete de documentación.
Propuesta
Actualiza el archivo README para guiar de forma más clara al nuevo lector a través del proyecto, incluidos los primeros pasos claros. Uno de esos primeros pasos sería leer y responder las preguntas de una nueva Guía de IA. Esa guía invitaría al lector a considerar el público, el esquema del contenido, las matrices de usuarios/tareas, etc., sin poner demasiado carga en el lector para aprender/entender qué son esos aspectos en el sentido académico. Una vez completada esta tarea, el lector comprende qué plantillas se requieren y cuál es la mejor manera de completarlas.
Investigación
Para respaldar esto con la investigación, me apoyaría bastante en el libro de Abby Covert (http://www.howtomakesenseofanymess.com/), en parte porque estoy muy familiarizado con él y ha sido la base de una gran cantidad de contenido que ya escribí y del que voy a utilizar, pero también porque es muy fácil para las personas nuevas de la IA captar y leer si tienen más interés. En ese sentido, es como un medicamento de puerta de enlace de IA.
ToC preliminar
README:
-- Introducción al buen proyecto de Documentos |_ Quién debe usar las plantillas |_ Cómo funcionan las plantillas |_ Hacer aportes al proyecto -- Las plantillas |_ Lista de todas las plantillas actuales |_ Elegir qué plantillas usar |_ Antes de comenzar -- Antes de comenzar a escribir |_ ¿Quién lee los documentos? |_ ¿Por qué leen los documentos? |_ Escritura para tus lectores
Guía de IA:
-- Introducción |_ ¿Qué es la AI? |_ ¿Por qué debería importarme? -- Identificar el lío -- Indicar tu intención -- La realidad de la cara -- Elige una dirección -- Mide la distancia -- Juega con la estructura -- Prepárate para ajustarte