Escribí un libro entero sobre este tema. Se llama Cada página es la primera página: redacción basada en temas para la comunicación técnica y la Web . En él analizo la investigación sobre cómo las personas usan la información técnica y cómo la web cambia la forma en que usamos la información en general, y propongo siete principios para el diseño de temas.

Una de las cosas que analicé en profundidad al preparar el libro fue el tema de la extensión. Mi conclusión fue que la longitud no es una forma útil de abordar el problema. En cambio, deberíamos pensar en términos de lo que en ingeniería de software se llama cohesión: la medida en que todas las piezas de un módulo pertenecen juntas.

Un tema cohesivo resuelve un problema de usuario. (No necesariamente todo el problema con el que vinieron, que puede estar compuesto por varios subproblemas, sino un problema discreto). La cantidad de información necesaria para crear un tema cohesivo que aborde un problema puede variar sustancialmente. Por lo tanto, la longitud no es una medida útil.

Mis siete principios del diseño Cada página es una página están destinados a brindar orientación en la creación de temas cohesivos. Seguir estos principios debería conducir a temas que tengan la extensión adecuada para el trabajo que tienen que hacer. Los siete principios son:

1. Un tema EPPO es autónomo. No tiene necesariamente un tema anterior o siguiente.

2. Un tema de la EPPO tiene un propósito específico y limitado.

3. Un tema EPPO se ajusta a un tipo. Cuando haya logrado un diseño de tema cohesivo, encontrará que cada tema de ese tipo sigue el mismo patrón, ya que las mismas necesidades de información ocurren en cada instancia. Una vez que discierna el patrón, puede usarlo para guiar la escritura de temas futuros.

4. Los temas de una EPPO establecen el contexto. Debido a que es el primer tema que puede leer un lector, un tema debe establecer su contexto para que el lector sepa dónde está y qué tipo de información puede esperar.

5. Un tema de EPPO asume que el lector está calificado. Esto puede parecer contrario a la intuición, pero si no asume un cierto nivel razonable de competencia en el lector, terminará tratando de explicar todo y su tema se convertirá en un libro. Usted apoya a los lectores que no están calificados refiriéndolos a otros temas.

6. Un tema de la EPPO se mantiene en un nivel. Diferentes lectores buscan diferentes niveles de información en diferentes momentos en su viaje hacia la comprensión. Deje que los lectores elijan cuándo cambiar de nivel cambiando de tema. De lo contrario, no podrá seguir los otros principios y sus temas carecerán de cohesión.

7. Los temas de la EPPO se vinculan ricamente. Cada tema está incrustado en un espacio temático mucho más amplio. Para mantener su tema coherente y centrado en un problema, no debe seguir presentando temas relacionados. Pero los lectores aún necesitan acceso rápido a esos temas relacionados. Los enlaces proporcionan ese acceso. En ingeniería de software, la otra cara de la cohesión es el acoplamiento débil. Los enlaces proporcionan el acoplamiento flexible que hace posible la cohesión de los temas.

En conclusión: La longitud es la medida incorrecta. Concéntrese en hacer que sus temas sean cohesivos y en vincularlos de manera rica. Esto producirá temas de diferentes longitudes, pero cada uno tendrá la longitud adecuada para el trabajo que tiene que hacer.

TL;DR

Las páginas cortas son mejores.

La estructura ideal

Recomendaría lo siguiente:

• Cada página debe tener un propósito único y claramente definido.
• Cada página debe tener una audiencia claramente definida.
• Las páginas deben estar vinculadas a otras páginas relevantes.
• Estructure sus páginas como un árbol, con páginas de descripción general más cerca de la raíz, proporcionando más detalles a medida que avanza hacia las hojas.
• Proporcione múltiples páginas de contenido que reflejen los roles e intereses de los lectores.
• Proporcionar una función de búsqueda completa
• Anime a los usuarios de la página a contribuir con los contenidos.

En mi experiencia, un wiki es un vehículo ideal para proporcionar estas características.

Justificación

• La mayoría de las personas encuentran páginas largas desalentadoras
• Es más fácil encontrar información en una página corta
• Las páginas de contenido ayudan a aclarar la estructura de la documentación.
• La descripción general y la inmersión profunda están separadas y es probable que sean consumidas por diferentes lectores (o lectores con diferentes niveles de conocimiento)
• Los programadores están familiarizados con esta estructura.
• Los árboles de contenido y la búsqueda hacen que esta estructura sea muy navegable.
• A nadie le importa hacer clic, especialmente a los programadores. La antigua regla de los dos clics simplemente ya no se aplica.
• Una buena búsqueda global hace que la búsqueda en la página sea menos importante
• Los documentos producidos en colaboración con sus lectores son generalmente mejores que los producidos por un solo autor.

Acerca de mí

Soy un programador con más de 20 años de experiencia en la industria. El equipo al que pertenezco produce parte de la mejor documentación que he visto. Hacemos esto usando un wiki basado en MediaWiki para toda nuestra documentación. Todos en el equipo contribuyen, editan, aclaran, corrigen, etc. Más importante aún, todos leemos la documentación, porque la hemos desarrollado juntos para satisfacer las necesidades que realmente tenemos, en lugar de las necesidades que alguien más pueda tener.