Orientações gerais de escrita

Siga estas orientações de escrita ao desenvolver conteúdos utilizando os modelos do The Good Docs Project

Linguagem e tom

  • Utilize linguagem, ortografia e tom consistentes em todos os seus documentos.

  • Descreva as coisas da forma mais clara e precisa possível.

  • Passe o seu texto por um verificador gramatical (linter) para verificar a sua legibilidade.

    • Ferramentas como o Grammarly ajudam-no a identificar problemas gramaticais

    • Ferramentas como o Vale ajudam-no a identificar problemas de estilo.

    • Este artigo inclui uma lista de outras ferramentas de verificação.)

  • Evite coloquialismos e jargões, pois dificultam a compreensão do que diz a quem não é falante nativo do idioma.

  • Evite incluir siglas na documentação sem escrever o termo por extenso na primeira vez que aparecem. Pode usar a sigla em referências posteriores.

  • Evite incluir as suas próprias opiniões ou as de terceiros. Isto prejudica a capacidade do leitor de tirar conclusões a partir da documentação.

Escrita de passos procedimentais

Aqui estão algumas recomendações que pode utilizar ao criar passos procedimentais:

  • Para procedimentos com muitos passos, considere dividir o conteúdo em subsecções de 5 a 10 passos. Isto torna a informação mais fácil de ler e memorizar, além de proporcionar ao leitor uma sensação de realização após a conclusão de cada bloco. Esta prática de fragmentação de conteúdos é recomendada por grandes empresas — como no guia de estilo de escrita da Microsoft — e tem suporte em pesquisas do Nielsen Norman Group sobre fragmentação e usabilidade.

  • Cada passos consiste numa única frase (deve conseguir lê-la em voz alta, e deve fazer sentido gramatical).

  • Ao descrever um passo, inclua uma frase introdutória para lembrar o leitor do que fará ao seguir os subpassos.

  • Procure não incluir mais de quatro subpassos em nenhum passo principal.

  • Se estiver a recuar subpassos para além de um nível de recuo, separe os passos num novo bloco de passo principal.

  • Um número excessivo de subpassos pode indicar a necessidade de desmembrar alguns deles numa nova secção de passos.

  • Recomenda-se o uso de capturas de ecrã e imagens, especialmente se puder incluir destaques para as partes específicas do ecrã a que se está a referir.

  • Identifique os passos opcionais digitando Opcional seguido de dois pontos. Por exemplo,

    • Opcional: Introduza uma descrição para o seu repositório.

  • Utilize condições se (condição) então (resultado) para identificar os passos aplicáveis apenas se forem cumpridos determinados critérios. Inicie sempre os passos condicionais com uma condição, para que os utilizadores que não a cumpram possam ignorar a etapa. Por exemplo,

    • Se é utilizador do Windows, instale o software VM VirtualBox na sua máquina.

Para mais informações sobre a redação de procedimentos, consulte o guia de estilo da documentação para programadores do Google.

Estrutura da página

  • Crie um esboço dos títulos que pretende incluir no documento antes de começar a escrever.

    • Utilize o esboço para organizar as suas ideias sobre os tópicos principais que precisa de transmitir aos seus leitores.

    • É muito mais fácil reorganizar os itens utilizando títulos do que mover blocos de conteúdo.

  • Também pode perceber que precisa de criar dois artigos se o assunto começar a ramificar.

  • Inclua na secção “Ver também” todos os links mencionados no corpo do conteúdo. Os links inseridos diretamente no texto podem passar despercebidos em artigos longos, e a necessidade de os procurar aumenta a carga cognitiva do seu público.

Títulos e nomes de ficheiros

  • Torne o título descritivo do conteúdo do artigo.

  • Torne o título único dentro do espaço da sua aplicação.

  • Utilize o mesmo nome para o título e para o ficheiro: torna-se difícil identificar o nome do ficheiro quando o título e o nome do ficheiro são diferentes.

  • Utilize palavras únicas nos títulos para que possa pesquisar e substituir texto mais tarde sem obter correspondências imprecisas.

Aqui estão alguns exemplos de títulos e as estruturas de nomes de ficheiros sugeridas para os mesmos:

  • Usando uma torradeira

    • usando-uma-torradeira.rst

  • Toste uma fatia de pão

    • toste-fatia-de-pão.rst

Definições

Se estiver a utilizar termos repetidamente ao longo de um artigo extenso, pode defini-los uma única vez e, em seguida, utilizá-los repetidamente no corpo do artigo.

Explore outros guias e modelos do The Good Docs Project.