Projet GoodDocs

Cette page contient les détails d'un projet de rédaction technique accepté pour la saison des documents Google.

Résumé du projet

Organisation Open Source:

TheGoodDocsProject

Rédacteur technique:

Loquacité

Nom du projet:

Guide sur l'architecture de l'information

Durée du projet:

Durée standard (trois mois)

Project description

Plan du guide d'architecture de l'information

Ce document couvre la planification d'un guide d'architecture des informations pour le projet Good Docs. Il a été préparé dans le cadre d'un envoi pour la Google Season of Docs 2020. Il décrit le cas d'utilisation du guide proposé et esquisse un plan de la structure d'un tel guide, à des fins de planification.

L'architecture de l'information (AI) concerne l'organisation du contenu. Il couvre la structure du contenu sans définir le style ni les mots utilisés dans le contenu lui-même. Par exemple, un plan d'IA doit tenir compte de l'identité du lecteur, de la façon dont il aborde le contenu et de l'environnement dans lequel il lit. Il peut ensuite envisager d'adopter une structure de contenu adaptée à ces besoins.

Dans un monde idéal, la conception de la documentation commence par une stratégie de contenu, qui utilise les objectifs commerciaux pour définir les objectifs de la documentation. La stratégie de contenu est ensuite utilisée pour créer une AI, qui définit la mise en page et la structure de la documentation. Vous pouvez ensuite choisir des chaînes d'outils et écrire du contenu. Dans la réalité, la stratégie de contenu de la plupart des projets Open Source se résume à "écrire de la documentation pour que les utilisateurs sachent comment utiliser ce projet". Mais même cette stratégie simple suffit à définir une IA efficace.

L'objectif de ce guide est de fournir un outil simplifié aux rédacteurs non professionnels pour qu'ils puissent développer une IA suffisante pour déterminer les modèles à utiliser. Il doit être suffisamment simple pour être réalisé par un humain ordinaire en une après-midi et doit privilégier l'action à l'éducation. Idéalement, il doit présenter les concepts de manière succincte, guider le lecteur à considérer ces concepts par rapport à leur propre projet et utiliser le résultat de cette présentation pour passer au concept suivant.

En guise d’échafaudage pour ce projet, certaines mises à jour du fichier README du projet sont nécessaires, afin que les lecteurs comprennent comment démarrer avec le projet Good Docs et puissent utiliser efficacement le guide d’AI pour guider leurs choix de modèles.

Audience principale

Toutes les personnes qui souhaitent utiliser les modèles du projet Good Docs pour créer la documentation de leur projet

Cas d'utilisation : Cette section est conçue pour explorer la façon dont les lecteurs abordent le guide de l'AI. Cela nous aidera à identifier la structure du guide afin de répondre au mieux aux besoins de ces lecteurs.

Scénario : Une personne travaille sur un projet Open Source qui ne dispose que de peu ou pas de documentation, ou dont la documentation est mal organisée ou mal rédigée. Il décide d'utiliser The Good Docs Project pour organiser sa documentation, mais ne sait pas par où commencer. Il suit le fichier README pour comprendre comment se lancer avec les modèles, et le Information Architecture Guide pour développer sa stratégie de contenu et planifier l'apparence de sa suite de documentation.

Proposition

Mettez à jour le fichier README pour guider plus clairement le nouveau lecteur dans le projet, y compris en indiquant clairement les premières étapes. L'une de ces premières étapes consiste à lire et à répondre aux questions d'un nouveau guide sur l'IA. Ce guide inviterait le lecteur à prendre en compte l'audience, le schéma de contenu, les matrices utilisateur/tâche, etc., sans trop solliciter le lecteur pour qu'il apprenne/comprend ces éléments d'un point de vue académique. Une fois cette tâche terminée, le lecteur comprend quels modèles sont requis et comment les remplir au mieux.

Research

Pour étayer cette affirmation, je m'appuierai principalement sur le livre d'Abby Covert (http://www.howtomakesenseofanymess.com/), en partie parce que je le connais très bien et qu'il a servi de base à de nombreux contenus que j'ai déjà écrits et que j'utiliserai, mais aussi parce qu'il est très facile à lire pour les personnes qui ne connaissent pas l'IA. Dans ce sens, c'est un peu une drogue d'entrée dans l'IA.

Brouillon de sommaire

LISEZ-MOI :

-- Présentation du projet Good Docs |_ Qui doit utiliser les modèles |_ Fonctionnement des modèles |_ Contribuer au projet -- Les modèles |_ Liste de tous les modèles actuels |_ Choisir les modèles à utiliser |_ Avant de commencer -- Avant de commencer à écrire |_ Qui lit les documents ? |_ Pourquoi lit-il la documentation ? |_ Écrire pour vos lecteurs

Guide de l'IA:

-- Introduction |_ Qu'est-ce que l'IA ? |_ Pourquoi est-ce important ? -- Identifier le désordre -- Définir votre objectif -- Faire face à la réalité -- Choisir une direction -- Mesurer la distance -- Jouer avec la structure -- Se préparer à ajuster