El proyecto TheGoodDocsProject

Esta página contiene los detalles de un proyecto de redacción técnica aceptado para la GDOC Season of Docs.

Resumen del proyecto

Organización de código abierto:
TheGoodDocsProject
Redactor técnico:
Logros
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

En este documento, se describe la planificación de una guía de arquitectura de la información para el proyecto Good Docs. Se preparó como parte de un envío de la Temporada de Documentos de Google de 2020. Describe el caso de uso de la guía propuesta y esboza un plan de la estructura de esa guía con fines de planificación.

La arquitectura de la información (AI) se relaciona con la forma en que se organiza el contenido. Abarca la estructura del contenido sin definir el estilo ni las palabras que se usan en el contenido. Por ejemplo, un plan de AI tendría en cuenta quién es el lector, cómo se acerca al contenido y el entorno en el que lo lee. Entonces, consideraría una estructura adecuada para el contenido que mejor se adaptaría a estos requisitos de los lectores.

En un mundo ideal, la documentación se diseña comenzando con una estrategia de contenido, que usa 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 las cadenas de herramientas y escribir el contenido. La realidad de 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 usar este proyecto”, pero incluso esa estrategia simple es suficiente para poder definir una AI eficaz.

El objetivo de esta guía es proporcionar una herramienta simplificada para que los escritores no profesionales desarrollen una IA que sea suficiente para determinar qué plantillas deben usar. Debe ser lo suficientemente simple para que una persona común pueda completarlo en una tarde y debe priorizar la acción sobre la educación. Idealmente, presentará los conceptos de forma concisa, guiará al lector para que los considere en relación con su propio proyecto y usará el resultado de eso para pasar al siguiente concepto.

Como andamiaje para este proyecto, se requieren algunas actualizaciones del archivo readme del proyecto para que los lectores comprendan cómo comenzar a usar el proyecto Good Docs y puedan usar la guía de AI de manera eficaz para guiar sus elecciones 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 la AI. Esto nos puede ayudar a identificar cómo se debe estructurar la guía para ofrecer un mejor servicio a esos lectores.

Situación: Una persona está trabajando en un proyecto de código abierto que tiene poca documentación o no tiene ninguna, o bien un paquete de documentación que está mal organizado o escrito. Decide usar The Good Docs Project para organizar su documentación, pero no sabe por dónde empezar. Sigue el archivo README para comprender cómo comenzar a usar las plantillas y sigue el Information Architecture Guide para desarrollar su estrategia de contenido y planificar cómo será su paquete de documentación.

Propuesta

Actualiza el archivo Léeme para guiar con más claridad al lector nuevo 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 de contenido, las matrices de usuarios o tareas, etc., sin sobrecargarlo con la necesidad de aprender o comprender qué son esas cosas en un sentido académico. Una vez que se completa esta tarea, el lector comprende qué plantillas son necesarias y cómo completarlas de la mejor manera.

Investigación

Para respaldar esto con investigación, me basaría en gran medida en el libro de Abby Covert (http://www.howtomakesenseofanymess.com/), en parte porque estoy muy familiarizado con él y ha sido la base de mucho contenido que ya escribí y usaré, pero también porque es muy fácil para las personas que recién comienzan en la AI tomar y leer si tienen más interés. En ese sentido, es una droga de puerta de enlace de IA.

Borrador del TDC

README:

-- Introducción al proyecto de documentos de calidad |_ Quién debería usar las plantillas |_ Cómo funcionan las plantillas |_ Cómo contribuir al proyecto -- Las plantillas |_ Lista de todas las plantillas actuales |_ Cómo elegir qué plantillas usar |_ Antes de comenzar -- Antes de empezar a escribir |_ ¿Quién lee los documentos? |_ ¿Por qué leen los documentos? |_ Cómo escribir para tus lectores

Guía de IA:

-- Introducción |_ ¿Qué es la IA? |_ ¿Por qué debería importarme? -- Identifica el desorden -- Expresa tu intención -- Enfréntate a la realidad -- Elige una dirección -- Mide la distancia -- Juega con la estructura -- Prepárate para hacer ajustes