Esta página contém os detalhes de um projeto de escrita técnica aceito para a temporada de documentos do Google.
Resumo do projeto
- Organização de código aberto:
- WordPress
- Redator técnico:
- tacitônico
- Nome do projeto:
- Um conjunto completo e renovado de guias de estilo de documentação
- Duração do projeto:
- De longa duração (5 meses)
Project description
Sinopse:
O WordPress é uma organização de software global sem fins lucrativos dedicada a atender às comunidades globais com software que enfatiza acessibilidade, desempenho, segurança e facilidade de uso. A causa do WordPress se esforça para democratizar a publicação e o software de código aberto na Web. Na nossa era digital, um site é literalmente a fachada on-line de uma organização/indivíduo. O WordPress desempenha uma imensa tarefa de atender, com eficiência, centenas de milhões de usuários (atribuídos aos 35% da Internet) com o software. Para atender melhor esses usuários, a documentação é essencial e usada pela maioria dos desenvolvedores, administradores e usuários finais. Portanto, a documentação pode ser definida como um fator principal do ecossistema 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 motivo desta proposta é criar um conjunto completo e renovado de diretrizes de estilo de documentação, universalmente aplicáveis à documentação do WordPress. A ideia do projeto envolve consolidar todos os aspectos das diretrizes de design e estilo, como semântica, sintática, diretrizes gramaticais, pontuação, regras específicas para desenvolvimento, atributos de design e detalhes de formatação. Ele também incorpora convenções de linguagem, como voz, tom, tempo, todas as classes gramaticais e convenções de nomenclatura. As ferramentas, linguagens e plataformas usadas serão CMS do WordPress, GitHub, Markdown e também podem consistir em PHP/MySQL, HTML/CSS e JavaScript.
Plano do projeto:
Guias de estilo de documentação do estado atual do WordPress: a equipe de documentação do WordPress vem implementando uma metodologia não declarada, mas unanimidade, de diretrizes de publicação. Mas, de vez em quando, alguns elementos são pressupostos e o processo se torna especulativo. Não existe um padrão e um critério fixos para escrever e publicar artigos para o WordPress. A equipe de documentação criou diretrizes de estilo específicas para o projeto, mas nenhuma que seja universalmente aplicável. A maioria das diretrizes de estilo existentes não está consolidada em um manual ou foi descontinuada e precisa ser atualizada. Por isso, há a necessidade de criar 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 funcionalidades impressionantes do WordPress. A documentação é um elemento essencial para ajudar esses desenvolvedores e usuários a atender a essas funcionalidades com eficiência e sem complicações, mesmo em caso de inconvenientes. O objetivo geral da proposta de projeto é padronizar um guia de design e estilo, unificar e atualizar os guias de estilo existentes, bem como anexar novos regulamentos e especificações para a documentação do WordPress. Isso permitiria facilidade de uso, simplicidade e uniformidade na documentação do WordPress.
Implementação:
Conforme 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 de pré-estágio, vou trabalhar com meu mentor e finalizar um cronograma e um cronograma adequados de acordo com os próximos cronogramas e entregas. Vou me familiarizar mais com o sistema do WordPress e os protocolos de trabalho para este projeto.
Conforme o estágio começar, vou discutir e redigir o resumo do plano com meu mentor. Os requisitos e necessidades serão determinados. Primeiro, vou descrever o fluxo da documentação e o 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 revisados pelo meu mentor. Se necessário, os layouts serão reformulados e alguns componentes serão adicionados/removidos. Em seguida, realizarei uma pesquisa com usuários para determinar a usabilidade e a viabilidade do fluxo da interface. Em seguida, o Guia de estilo da documentação será implementado (conforme ilustrado no diagrama abaixo) por seção. Guias de estilo de outras organizações que estão sob qualquer licença de código aberto ou Creative Commons podem ser consultados para anexar nosso guia. Se houver dificuldades de usabilidade durante esse período, elas serão reformuladas.
Os testes e as otimizações são realizados depois que o guia de estilo é concluído e integrado ao HelpHub. Quaisquer vulnerabilidades, elementos ou componentes redundantes serão retificados. Vamos realizar testes de interface e código e corrigir bugs e erros indesejados, se necessário. Será realizado um controle de qualidade final para o guia de estilo completo com relação a idioma, gramática, ortografia, pontuação etc.
As tarefas pendentes devido a atrasos imprevistos são concluídas no período de espera. Após a conclusão dos testes finais, outras funcionalidades ou recursos que seriam considerados viáveis ao longo do projeto podem ser implementados. Um plano de implantação será criado e o produto final será enviado.
Ferramentas e metodologias:
A documentação será compilada e editada em uma plataforma colaborativa, como o Google Docs. Se necessário para publicar pelo GitHub, linguagens de marcação como Markdown ou GitHub Flavored Markdown também podem ser implementadas. Para padrões de design e estilo, as diretrizes de estilo de código aberto também podem ser referenciadas. Por fim, o documento completo seria formatado e publicado usando o WordPress.
Tabela de componentes:
Esta é uma lista completa dos componentes que podem ser implementados no Guia de estilo. Diretrizes do documento: acessibilidade, estrutura do documento, codificação, fontes externas, fatos, fontes, público global, inclusão, legalidade, acessibilidade em várias plataformas, não ambíguo, sem declarações excessivas, layout da página, correção política, protocolos, segurança, estrutura das frases, redação sucinta, tom e estilo, imparcial
Linguagem e gramática - abreviações e acrônimos, afirmação e negação, artigos, letras maiúsculas, cláusula, discurso direto/indireto, primeira/segunda/terceira pessoa, gêneros, glossário, substantivos, prefixos e sufixos, preposições, pronomes, referências, gírias e jargões, ortografias, termos técnicos, voz
Pontuação: apóstrofo e aspas, dois pontos e semi-pontos, vírgulas, elipses, pontos de exclamação, hífens e traços, parênteses, pontos, pontos de interrogação, barras
Formatação, resumos, introdução, 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, destaques (negrito, itálico, sublinhado, tachado, números, anotações, índice, pontos e URLs de tradução, anotações, índice, pontos e URLs, listas
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
Dicionário/Glossário de uso de palavras - de A a Z