Projet GoodDocs

Cette page contient les détails d'un projet de rédaction technique accepté pour Google Season of Docs.

Résumé du projet

Organisation Open Source:

TheGoodDocsProject

Rédacteur technique:

Loquacité

Nom du projet:

Guide d'architecture des informations

Durée du projet:

Durée standard (3 mois)

Project description

Plan du guide sur l'architecture des informations

Ce document couvre la planification d'un guide d'architecture des informations pour le projet Good Docs. Il a été préparé lors d'un envoi à 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 des informations (AI) concerne la façon dont le contenu est organisé. Il couvre la structure du contenu sans définir le style ou les mots utilisés dans le contenu lui-même. Par exemple, un plan d’AI tient compte de qui est le lecteur, de la façon dont il aborde le contenu et de l’environnement dans lequel il lit. Elle a ensuite pensé à définir la structure de contenu la mieux adaptée aux attentes des lecteurs.

Dans un monde parfait, la documentation est conçue en commençant par une stratégie de contenu, qui utilise des 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. À partir de là, vous pouvez choisir des chaînes d'outils et écrire du contenu. La réalité de la plupart des projets open source est que la stratégie de contenu est aussi simple que « rédiger de la documentation afin que les gens sachent comment utiliser ce projet », mais même cette stratégie simple est suffisante pour pouvoir définir une AI efficace.

L'objectif de ce guide est de fournir un outil simplifié permettant aux rédacteurs non professionnels d'élaborer une AI qui soit suffisante pour déterminer les modèles à utiliser. Il doit être suffisamment simple pour être terminé par un humain ordinaire en une après-midi et doit favoriser l'action plutôt que l'éducation. Idéalement, elle présentera des concepts de manière succincte, guidera le lecteur à envisager ces concepts en lien avec son propre projet et en exploitera le résultat pour passer au concept suivant.

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

Audience principale

Toutes les personnes souhaitant utiliser les modèles du projet The Good Docs pour créer des documents sur leur projet

Cas d'utilisation : cette section est conçue pour explorer la façon dont les lecteurs abordent le guide d'IA. Cela peut nous aider à déterminer comment le guide doit être structuré afin de mieux répondre aux besoins de ces lecteurs.

Scénario : Une personne travaille sur un projet Open Source avec peu ou pas de documentation, ou une suite de documentation mal organisée ou mal rédigée. Elle décide d'utiliser le projet Good Docs pour organiser sa documentation, mais ne sait pas par où commencer. Ils suivent le fichier README pour commencer à utiliser les modèles, puis suivent le Information Architecture Guide pour développer leur stratégie de contenu et planifier l'aspect de leur suite de documentation.

Proposition

Mettez à jour le fichier README pour guider plus clairement le nouveau lecteur tout au long du projet, y compris pour les premières étapes claires. L'une de ces premières étapes consisterait à lire et à répondre aux questions dans un nouveau guide de l'AI. Ce guide invite le lecteur à prendre en compte l'audience, le schéma de contenu, les matrices utilisateur/tâche, etc., sans lui demander trop d'efforts pour apprendre/comprendre ces points 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 réaliser au mieux.

Recherches

Pour étayer cela avec la recherche, je m'appuierais assez fortement sur le livre d'Abby Covert (http://www.howtomakesenseofanymess.com/), en partie parce que je le connais très bien et qu'il est à la base d'un grand nombre de contenus que j'ai déjà écrit et que je vais utiliser, mais aussi parce qu'il est très facile pour les personnes qui débutent avec l'AI de le comprendre et de le lire. C'est un peu un médicament de passerelle d'AI, dans ce sens.

Version préliminaire des conditions de travail

LISEZ-MOI :

-- Introduction au projet Good Docs |_ Qui doit utiliser les modèles |_ Fonctionnement des modèles |_ Contribuer au projet -- 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 lisent-ils les documents ? |_ Rédiger du contenu pour vos lecteurs

Guide AI:

-- Introduction |_ Qu'est-ce que l'AI ? |_ Pourquoi s'en préoccuper ? -- Identifier le désordre -- Exprimez votre intention -- Affrontez la réalité -- Choisissez une direction -- Mesurez la distance -- Jouez avec la structure -- Préparez-vous à vous adapter