Projeto TheGoodDocsProject

Esta página contém os detalhes de um projeto de redação técnica aceito para a Google Season of Docs.

Resumo do projeto

Organização de código aberto:

TheGoodDocsProject

Redator técnico:

Loquacidade

Nome do projeto:

Guia de arquitetura da informação

Duração do projeto:

Duração padrão (3 meses)

Project description

Plano de guia de arquitetura da informação

Este documento aborda o planejamento de um guia de arquitetura da informação para o projeto Good Docs. Ele foi preparado como parte de um envio do Google Season of Docs 2020. Ele descreve o caso de uso do guia proposto e esboça um plano da estrutura desse guia para fins de planejamento.

A arquitetura da informação (AI) se refere à organização do conteúdo. Ele abrange a estrutura do conteúdo sem definir o estilo ou as palavras usadas no próprio conteúdo. Por exemplo, um plano de AI consideraria quem é o leitor, como ele aborda o conteúdo e o ambiente em que está lendo. Em seguida, ele considera uma estrutura apropriada para o conteúdo que atende melhor a esses requisitos dos leitores.

Em um mundo perfeito, a documentação é projetada começando com uma estratégia de conteúdo, que usa metas de negócios para definir as metas da documentação. A estratégia de conteúdo é usada para criar uma IA, que define o layout e a estrutura da documentação. A partir daí, é possível escolher as cadeias de ferramentas e escrever o conteúdo. A realidade da maioria dos projetos de código aberto é que a estratégia de conteúdo é tão simples quanto "escrever documentação para que as pessoas saibam como usar o projeto", mas mesmo essa estratégia simples é suficiente para definir uma AI eficaz.

O objetivo deste guia é fornecer uma ferramenta simplificada para que escritores não profissionais desenvolvam uma IA suficiente para determinar quais modelos devem ser usados. Ele precisa ser simples o suficiente para ser concluído por uma pessoa comum em uma tarde e deve favorecer a ação em vez da educação. O ideal é que ele introduza conceitos de forma sucinta, orienta o leitor a considerar esses conceitos em relação ao próprio projeto e usa o resultado para passar para o próximo conceito.

Como estrutura para este projeto, algumas atualizações no README do projeto são necessárias para que os leitores entendam como começar a usar o projeto Good Docs e possam usar o guia de IA de forma eficaz para orientar as escolhas de modelos.

Público-alvo principal

Todas as pessoas que querem usar os modelos do projeto Good Docs para criar a documentação do projeto

Casos de uso: esta seção foi criada para mostrar como os leitores abordam o Guia de IA. Isso pode nos ajudar a identificar como o guia deve ser estruturado para atender melhor esses leitores.

Cenário: uma pessoa está trabalhando em um projeto de código aberto que tem pouca ou nenhuma documentação ou um conjunto de documentação mal organizado ou escrito. Ela decide usar o projeto Good Docs para organizar a documentação, mas não sabe por onde começar. Eles seguem o arquivo README para entender como começar a usar os modelos e seguem o Information Architecture Guide para desenvolver a estratégia de conteúdo e planejar a aparência do pacote de documentação.

Proposta

Atualize o README para orientar melhor o novo leitor pelo projeto, incluindo as primeiras etapas. Uma das primeiras etapas é ler e responder às perguntas em um novo guia de IA. Esse guia convida o leitor a considerar o público-alvo, o esquema de conteúdo, as matrizes de usuários/tarefas etc., sem sobrecarregar o leitor com a necessidade de aprender/entender o que essas coisas são em um sentido acadêmico. Depois de concluir essa tarefa, o leitor vai entender quais modelos são necessários e como concluí-los da melhor forma.

Pesquisa

Para comprovar isso com pesquisas, eu me basearia bastante no livro de Abby Covert (http://www.howtomakesenseofanymess.com/), em parte porque estou muito familiarizado com ele e ele serviu de base para muito conteúdo que já escrevi e vou usar, mas também porque é muito fácil para pessoas novas na IA pegar e ler se tiverem interesse. É uma droga de entrada para a IA, nesse sentido.

Draft ToC

LEIA-ME:

-- Introdução ao projeto Good Docs |_ Quem deve usar os modelos |_ Como os modelos funcionam |_ Como contribuir para o projeto -- Os modelos |_ Lista de todos os modelos atuais |_ Como escolher os modelos a serem usados |_ Antes de começar -- Antes de começar a escrever |_ Quem lê os documentos? |_ Por que eles leem os documentos? |_ Como escrever para seus leitores

Guia de IA:

-- Introdução |_ O que é IA? |_ Por que isso é importante? -- Identificar a bagunça -- Informar sua intenção -- Realidade facial -- Escolher uma direção -- Medir a distância -- Brincar com a estrutura -- Preparar-se para ajustar