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:
- WordPress
- Redator técnico:
- Tacitonia
- Nome do projeto:
- Um guia de estilo de documentação completo e renovado
- Duração do projeto:
- Longa duração (cinco meses)
Project description
Sinopse:
O WordPress é uma organização global de software sem fins lucrativos dedicada a atender as comunidades globais com software que enfatiza acessibilidade, desempenho, segurança e facilidade de uso. A causa do WordPress busca democratizar a publicação e o software de código aberto na Web. Na era digital, um site é literalmente a fachada on-line de uma organização ou pessoa. O WordPress tem a imensa tarefa de atender centenas de milhões de usuários de forma eficiente com o software, que representa 35% da Internet. Para atender esses usuários de maneira mais eficiente, a documentação é essencial e é usada pela maioria dos desenvolvedores, administradores e usuários finais. Portanto, a documentação pode ser estabelecida como um fator principal do ecossistema do WordPress. A documentação atual do WordPress não inclui um conjunto universal e unificado de regras e diretrizes de estilo para publicação. O objetivo desta proposta é criar um conjunto completo e renovado de diretrizes de estilo de documentação, aplicável universalmente à documentação do WordPress. A ideia do projeto envolve a consolidação de todos os aspectos das diretrizes de design e estilo, como semântica, sintática, diretrizes gramaticais, pontuação, regras específicas do desenvolvimento, atributos de design e detalhes de formatação. Ele também incorpora convenções de linguagem, como voz, tom, tempo, todas as partes do discurso e convenções de nomenclatura. As ferramentas, linguagens e plataformas usadas serão o CMS do WordPress, o GitHub, o Markdown e podem incluir PHP/MySQL, HTML/CSS e JavaScript.
Plano do projeto:
Estado atual dos guias de estilo da documentação do WordPress: a equipe de documentação do WordPress tem implementado uma metodologia não declarada, mas unânime, de publicação de diretrizes. Mas, de vez em quando, alguns elementos se sobrepõem e o processo se torna especulativo. Não existe um padrão ou critério fixo para escrever e publicar artigos no WordPress. A equipe de documentação escreveu diretrizes de estilo específicas do projeto, mas nenhuma delas é universalmente aplicável. A maioria das diretrizes de estilo disponíveis não está consolidada em um manual ou está descontinuada e precisa ser atualizada. Portanto, é necessário projetar e desenvolver um guia de estilo unificado para padronizar a documentação do WordPress.
Objetivos:
Mais de 35% dos sites da Internet são executados no WordPress, o que indica que milhões de desenvolvedores e usuários finais estão usando as funcionalidades impressionantes do WordPress. A documentação é um elemento essencial para ajudar esses desenvolvedores e usuários a cumprir essas funcionalidades de maneira eficiente, sem complicações, mesmo em caso de inconvenientes. O objetivo geral desta proposta de projeto é padronizar um guia de design e estilo, unificar os guias de estilo atuais e atualizar, bem como anexar novas regulamentações e especificações para a documentação do WordPress. Isso permitiria facilidade de uso, simplicidade e uniformidade na documentação do WordPress.
Implementação:
Como sugerido pelo mentor (Jon Ang) para este projeto, ele pode ser abordado em quatro fases: descoberta, definição, implementação e manutenção. Antes do início do projeto, durante o período pré-estágio, vou trabalhar com meu mentor e finalizar um cronograma e uma programação adequados de acordo com minha programação e entregas subsequentes. Vou me familiarizar mais com o sistema WordPress e os protocolos de trabalho para este projeto.
No início do estágio, vou discutir e elaborar o resumo do plano com meu mentor. Os requisitos e as necessidades serão determinados. Primeiro, vou descrever o fluxo da documentação e do processo de interação do usuário. Em seguida, serão descritos os wireframes de layout de cada seção, categoria e componente. Esses layouts serão analisados pelo meu mentor. Se necessário, os layouts serão redesenhados e alguns componentes serão adicionados/removidos. Em seguida, vou realizar uma pesquisa de usuário para determinar a usabilidade e a viabilidade do fluxo da interface. Em seguida, o Guia de estilo de documentação será implementado (conforme ilustrado no diagrama abaixo) por seção. Os guias de estilo de outras organizações que estão sob qualquer licença de código aberto ou Creative Commons também podem ser referenciados para anexar nosso guia. Se durante esse período ocorrerem dificuldades de usabilidade, vou redesenhá-las.
Os testes e otimizações serão realizados depois que o guia de estilo for concluído e integrado ao HelpHub. Todas as vulnerabilidades, elementos ou componentes redundantes seriam corrigidos. Os testes de interface e código serão realizados, e bugs e erros indesejados serão corrigidos, se necessário. Um controle de qualidade final do guia de estilo completo será realizado para verificar linguagem, gramática, ortografia, pontuação etc.
As tarefas pendentes devido a atrasos imprevisíveis seriam concluídas no período de buffer. Funcionalidades ou recursos adicionais que seriam considerados viáveis ao longo do projeto podem ser implementados após a conclusão do teste final. Um plano de implantação seria criado e o produto final seria enviado.
Ferramentas e metodologias:
A documentação será compilada e editada em uma plataforma colaborativa, como os Documentos Google. Se for necessário publicar pelo GitHub, linguagens de marcação como Markdown ou Markdown personalizado para o GitHub também podem ser implementadas. Para padrões de design e estilo, também é possível consultar diretrizes de estilo de código aberto. Por fim, o documento completo é formatado e publicado usando o WordPress.
Tabela de componentes:
Esta é uma lista completa dos componentes que podem ser implementados no Guia de estilo. Diretrizes dos documentos: acessibilidade, estrutura do documento, codificação, fontes externas, fatos, fontes, público global, inclusão, legalidade, acessibilidade multiplataforma, não ambíguo, sem reivindicações excessivas, layout da página, correção política, protocolos, segurança, estrutura de frases, escrita sucinta, tom e estilo, imparcial
Língua e gramática: abreviações e acrônimos, afirmação e negação, artigos, maiúsculas, cláusulas, discurso direto/indireto, primeira/segunda/terceira pessoa, gêneros, glossário, substantivos, prefixos e sufixos, preposições, pronomes, referência, gíria e jargão, ortografia, termos técnicos, tempo, verbos, voz
Pontuação: apóstrofo e aspas, dois pontos e ponto e vírgula, vírgulas, elipses, pontos de exclamação, hífens e traços, parênteses, pontos, pontos de interrogação e barras
Formatação: resumos, introduções, prefácios, nomes de marcas, nomes de produtos, legendas, snippets de código, blocos de código, data e hora, fusos horários, lugares, moedas, nomes de arquivos, notas de rodapé, títulos e títulos, realce (negrito, itálico, sublinhado, tachado, citação), recuo, índice, links e URLs, listas, marcadores de bullets, numeração, mídia (imagens, vídeos) e ilustrações, notas, avisos, dicas, números e números de telefone, poliglotas, tradução, scripts de linguagem, espaçamento, tabelas, texto, marcas registradas, direitos autorais, patentes, citações, tutoriais e procedimentos, elementos da interface, unidades de medida
Interface do usuário: atividades, botões, snippets de código, blocos de código, interface de linha de comando, caixas de diálogo, menus e menus suspensos, pop-ups e alertas, guias, terminologia, elementos da interface, janelas
Código: CSS, HTML, JS, Markdown, MySQL, PHP, sintaxe, XML
Glossário/dicionário de uso de palavras: de A a Z