Redação técnica para desenvolvedores

HTML, CSS, JavaScript, Python, PHP, C++, Dart — existem tantas linguagens de programação por aí e você pode até ser totalmente fluente em várias delas! Mas, à medida que pretendemos escrever mais e melhor código, a maneira como escrevemos e nos comunicamos na linguagem cotidiana se torna cada vez mais importante… e talvez até negligenciada.

A maneira como escrevemos sobre e em torno do código é indiscutivelmente tão importante quanto o próprio código. E apesar de onde você cai nessa linha, todos nós podemos concordar que nossas palavras têm o potencial de ajudar e prejudicar a eficácia do código.

Neste artigo, quero descrever como esses dois campos aparentemente distintos – programação e escrita – podem se unir e levar nossas habilidades de desenvolvedor para o próximo nível.

Espere, redação técnica? Sim, é exatamente isso que quero dizer. Eu realmente acredito que somos todos escritores em um sentido ou outro. E estou aqui para lhe dar uma cartilha com dicas de escrita, conselhos e exemplos de como isso pode torná-lo um melhor desenvolvedor e comunicador.

A redação técnica está em toda parte

No ano passado, a equipe por trás do popular cliente Mac Git, Tower, entrevistou mais de 4,000 desenvolvedores e descobriram que quase 50% deles gastavam entre 3-6 horas por dia escrevendo código.

E sim, essa é uma pesquisa com um grupo de nicho muito bonito, mas imagino que muitos de nós caiam em algum lugar nesse intervalo. Seja qual for o caso, um desenvolvedor não está escrevendo código 24 horas por dia, 7 dias por semana, porque, como esta pesquisa sugere, estamos gastando muito tempo fazendo outras coisas.

Isso pode incluir:

• demonstração de um novo recurso,
• documentar esse novo recurso,
• atualizar um ticket de trabalho relacionado a esse novo recurso ou
• trabalho de backlogging para dar suporte a esse novo recurso.

Claro, sempre há tempo para pausas no banheiro e Wordle também.

De qualquer forma, a maioria das coisas que normalmente fazemos envolve a comunicação com pessoas como sua equipe, colegas, clientes, usuários e outros desenvolvedores.

Então, nós gastamos uma boa parte do nosso tempo nos comunicando com humanos através de palavras além da comunicação que temos com computadores através código. Palavras são linguagem escrita. E se escrevêssemos melhor nossas palavras, nos comunicaríamos melhor. Quando nos comunicamos melhor, é mais provável que consigamos o que queremos.

Isso é Redação Técnica 101.

E nem acaba aqui. Alguns programadores também gostam de fazer seus próprios produtos, o que significa que precisam fazer do marketing parte de seu trabalho. A escrita técnica desempenha um papel enorme nisso também. Então sim. Acho muito justo dizer que a redação técnica é de fato em toda parte.

O que é uma boa gramática?

Com tantas linguagens de programação por aí, a última coisa que queremos é aprender outra.

Gramática é parte integrante do inglês e desbloqueia todo o potencial da comunicação. Isso nos torna mais formais, profissionais e coerentes.

Deixe-me dar-lhe um rápido resumo sobre a linguagem.

A sintaxe inglesa

Assim como as linguagens de programação, o inglês tem uma sintaxe bem definida e começa com palavras.

As palavras são os blocos de construção do inglês e se dividem em oito baldes:

Pense nisso como UI componentes: são peças modulares que você pode mover para construir uma frase completa e robusta, da mesma forma que você pode montar uma frase completa e robusta UI. Todos os componentes precisam estar lá o tempo todo? Certamente não! Monte uma frase com as peças que você precisa para completar a experiência, assim como faria com uma interface.

Voz e tom

Vocabulário, pontuação, estrutura de frases e escolha de palavras. Estes são todos os ingredientes do inglês. Nós os usamos para compartilhar ideias, nos comunicar com nossos amigos e familiares e enviar e-mails para nossos colegas de trabalho.

Mas é crucial considerar a som de nossas mensagens. É incrível como um ponto de exclamação pode mudar completamente o tom de uma mensagem:

1. Eu gosto de programação.
2. I como programação! :)

É fácil confundir voz com tom e vice-versa.

voz é o que diz respeito à nossa escolha de palavras, que depende do contexto. Por exemplo, é mais provável que um tutorial para iniciantes use gírias e linguagem informal para transmitir uma voz amigável, enquanto a documentação pode ser escrita de maneira formal, séria e profissional, em um esforço para ir direto ao ponto.

A mesma mensagem, escrita em duas vozes diferentes:

• Fun: “Expanda sua rede social e fique atualizado sobre o que está em alta agora.”
• Sério: “Encontre empregos em um dos maiores aplicativos de redes sociais e no mercado de empregos online.”

Não é incomum escrever acidentalmente mensagens que pareçam condescendentes, ofensivas e pouco profissionais. Este é o lugar onde tom entra em jogo. Leia suas mensagens em voz alta, faça com que outras pessoas os leiam para você e experimente sua pontuação e estrutura de frases. É assim que você aprimora seu tom.

Aqui está outra maneira de pensar nisso: sua voz nunca muda, mas seu tom sim. Sua voz é semelhante a quem você é como pessoa, enquanto o tom é como você responde em uma determinada situação.

voz ativa e passiva

Uma frase sempre contém um ator, um verbo e um alvo. A ordem em que vêm determina se a frase é escrita em voz ativa ou passiva.

O ator vem em primeiro lugar voz ativa. Por exemplo: “CSS pinta o plano de fundo”.

As frases que usam uma voz ativa são mais diretas do que suas contrapartes. Eles são mais claros, mais curtos e mais compreensíveis - perfeitos para uma voz mais profissional que vai direto ao ponto.

Com uma conta na voz passiva, o ator vem por último. (Veja o que eu fiz lá?) Isso significa que nosso ator - CSS neste caso - vem no final assim: "O plano de fundo é pintado por CSS".

Os leitores geralmente convertem uma voz passiva em uma voz ativa em suas cabeças, resultando em mais tempo de processamento. Se você já ouviu falar que escrever em voz ativa é melhor, geralmente esse é o motivo. Os redatores de tecnologia preferem a voz ativa na maioria das vezes, com poucas exceções, como citar pesquisas: “Foi sugerido que …”

Mas isso não significa que você deve sempre se esforçar para ter uma voz ativa. Alternar de um para o outro – mesmo no mesmo parágrafo – pode fazer com que seu conteúdo flua mais facilmente de uma frase para outra, se usado de forma eficaz.

Evitando erros

A gramática tem tudo a ver com a estrutura e correção da linguagem, e não há nada melhor para conseguir isso do que uma rápida revisão do seu documento. É muito importante livrar seus escritos de erros de ortografia, problemas gramaticais e imperfeições semânticas.

No final deste artigo, mostrarei as ferramentas inestimáveis ​​que os profissionais usam para evitar erros de escrita. Obviamente, existem verificadores ortográficos embutidos em quase tudo nos dias de hoje; nossos editores de código ainda têm plugins de verificação ortográfica e linting para ajudar a evitar erros. 

Mas se você está procurando uma ferramenta completa para gramática geral, Grammarly é uma das ferramentas mais utilizadas. Não estou recebendo propina por isso nem nada. É apenas uma ótima ferramenta que muitos editores e escritores usam para escrever conteúdo limpo e claro - semelhante a como você pode usar Emmet, eslint ou qualquer outro linter para escrever código limpo e claro.

Escrevendo comentários de código

As coisas que escrevemos para outros desenvolvedores podem ter um grande impacto na qualidade geral do nosso trabalho, seja o que escrevemos no código, como explicamos o código ou como damos feedback sobre um trecho de código.

É interessante que toda linguagem de programação venha com um conjunto padrão de recursos para escrever um comentário. Eles devem explicar o que o código está fazendo. Com isso, não quero dizer comentários vagos como este:

red *= 1.2 // Multiply `red` by 1.2 and re-assign it

Em vez disso, use comentários que forneçam mais informações:

red *= 1.2 // Apply a 'reddish' effect to the image

É tudo uma questão de contexto. “Que tipo de programa estou construindo?” é exatamente o tipo de pergunta que você deveria estar se fazendo.

Os comentários devem agregar valor

Antes de olharmos para o que faz um comentário de código “bom”, aqui estão dois exemplos de comentários preguiçosos:

const age = 32 // Initialize `age` to 32

filter: blur(32px); /* Create a blur effect with a 32px radius */

Lembre-se de que o objetivo de um comentário é agregar valor a um trecho de código, não repeti-lo. Se você não puder fazer isso, é melhor deixar o código como está. O que torna esses exemplos “preguiçosos” é que eles meramente reafirmam o que o código está obviamente fazendo. Nesse caso, os comentários são redundantes porque nos dizem o que já sabemos – eles não estão agregando valor!

Os comentários devem refletir o código atual

Comentários desatualizados não são raros em grandes projetos; ouso dizer em a maioria projetos.

Vamos imaginar David, um programador e um cara legal com quem sair. David quer ordenar uma lista de strings em ordem alfabética de A a Z, então ele faz o óbvio em JavaScript:

cities = sortWords(cities) // sort cities from A to Z

David então percebe que sortWords() realmente classifica as listas de Z para A. Isso não é um problema, pois ele pode simplesmente reverter a saída:

cities = sortWords(cities) // sort cities from A to Z
cities = reverse(cities)

Infelizmente, David não atualizou seu comentário de código.

Agora imagine que eu não te contei essa história, e tudo que você viu foi o código acima. Você naturalmente pensaria que depois de executar essa segunda linha de código, as `cidades` seriam classificadas de Z para A! Todo esse fiasco de confusão foi causado por um comentário obsoleto.

Embora isso possa ser um exemplo exagerado, algo semelhante pode (e geralmente acontece) acontecer se você estiver correndo contra um prazo apertado. Felizmente, isso pode ser evitado seguindo uma regra simples… altere seus comentários ao mesmo tempo em que altera o código.

Essa é uma regra simples que salvará você e sua equipe de muitos dívida técnica.

Agora que sabemos como são os comentários mal escritos, vamos ver alguns bons exemplos.

Os comentários devem explicar o código não idiomático

Às vezes o natural maneira de fazer as coisas não é certo. Os programadores podem ter que “quebrar” um pouco os padrões, mas quando o fizerem, é aconselhável deixar um pequeno comentário explicando sua lógica:

 function addSetEntry(set, value) {    
  /* Don't return `set.add` because it's not chainable in IE 11. */  
  set.add(value);
  return set;
}

Isso é útil, certo? Se você foi responsável por revisar este código, pode ter ficado tentado a corrigi-lo sem aquele comentário explicando o que está acontecendo.

Os comentários podem identificar tarefas futuras

Outra coisa útil a fazer com comentários é admitir que há mais trabalho a ser feito.

// TODO: use a more efficient algorithm
linearSort(ids)

Dessa forma, você pode manter o foco no seu fluxo. E em uma data posterior, você (ou outra pessoa) pode voltar e corrigi-lo.

Os comentários podem vincular de volta à fonte

Então, você acabou de encontrar uma solução para o seu problema no StackOverflow. Depois de copiar e colar esse código, às vezes é bom manter um link para a resposta que o ajudou para que você possa voltar a ela para referência futura.

// Adds handling for legacy browsers
// https://stackoverflow.com/a/XXXXXXX

Isso é importante porque as soluções podem mudar. É sempre bom saber de onde veio o seu código para o caso de ele quebrar.

Escrevendo solicitações de pull

Solicitações de pull (PRs) são um aspecto fundamental de qualquer projeto. Eles estão no centro das revisões de código. E as revisões de código podem rapidamente se tornar um gargalo no desempenho de sua equipe sem uma boa redação.

Um bem PR descrição resume o que mudança está sendo feita e porque está sendo feito. Projetos grandes têm um modelo de pull request, como este adaptado de um exemplo real:

## Proposed changes
Describe the big picture of your changes here to communicate to the maintainers why we should accept this pull request.

## Types of changes
What types of changes does your code introduce to Appium?
 - [ ] Bugfix (non-breaking change which fixes an issue)
 - [ ] New feature (non-breaking change which adds functionality)
 - ...

## Checklist
 - [ ] I have read the CONTRIBUTING doc
 - [ ] I have signed the CLA
 - [ ] Lint and unit tests pass locally with my changes

## Further comments
If this is a relatively large or complex change, kick off the discussion by explaining why you chose the solution you did and what alternatives you considered, etc…

Evite vagas PR títulos

Evite títulos assim:

• Corrija a compilação.
• Corrigir bug.
• Adicionar patch.

Esses nem mesmo tentativa para descrever com qual build, bug ou patch estamos lidando. Um pequeno detalhe extra sobre qual parte da compilação foi corrigida, qual bug foi eliminado ou qual patch foi adicionado pode ajudar bastante a estabelecer uma melhor comunicação e colaboração com seus colegas. Ele define o nível e coloca as pessoas na mesma página.

PR Os títulos são tradicionalmente escritos em tempo imperativo. Eles são um resumo de uma linha de todo o PR, e devem descrever o que está sendo feito pelo PR.

Aqui estão alguns bons exemplos:

• Suporta atributos srcset personalizados em NgOptimizedImage
• Configuração de imagem padrão para 75% de qualidade de imagem
• Adicione seletores explícitos para todos os ControlValueAccessors integrados

Evite longos PRs

Um grande PR significa uma descrição enorme, e ninguém quer revisar centenas ou milhares de linhas de código, às vezes apenas para acabar descartando a coisa toda!

Em vez disso, você poderia:

• comunicar com a sua equipa através Questões,
• faça um plano,
• quebrar o problema em pedaços menores, ou
• trabalhe em cada peça separadamente com seu próprio PR.

Não está muito mais limpo agora?

Forneça detalhes no PR corpo

Ao contrário do PR título, o corpo é que o lugar para todos os detalhes, incluindo:

• Porque é o PR sendo feito?
• Por que essa é a melhor abordagem?
• Quaisquer deficiências na abordagem e ideias para resolvê-las, se possível
• O número do bug ou ticket, resultados de benchmark, etc.

Relatando bugs

Relatórios de bugs são um dos aspectos mais importantes de qualquer projeto. E todos os grandes projetos são construídos com base no feedback do usuário. Normalmente, mesmo após inúmeros testes, são os usuários que encontram mais bugs. Os usuários também são ótimos idealistas e, às vezes, têm ideias de recursos; por favor, ouça-os!

Para projetos técnicos, tudo isso é feito relatando problemas. Um problema bem escrito é fácil para outro desenvolvedor encontrar e responder.

Por exemplo, a maioria dos grandes projetos vem com Uma amostra:

 <!-- Modified from angular-translate/angular-translate -->
 ### Subject of the issue
 Describe your issue here.

 ### Your environment
 * version of angular-translate
 * version of angular
 * which browser and its version

 ### Steps to reproduce
 Tell us how to reproduce this issue.

 ### Expected behavior
 Tell us what should happen.

 ### Actual behavior
 Tell us what happens instead.

Reúna capturas de tela

Capture o problema usando seu utilitário de captura de tela do sistema.

Se for uma captura de tela de um CLI programa, certifique-se de que o texto está claro. Se é um UI programa, certifique-se de que a captura de tela capture os elementos e estados corretos.

Pode ser necessário capturar uma interação real para demonstrar o problema. Se for o caso, tente gravar GIFs usando uma ferramenta de gravação de tela.

Como reproduzir o problema

É muito mais fácil para os programadores resolverem um bug quando ele está ativo em seu computador. É por isso que um bom commit deve vir com os passos para reproduzir precisamente o problema.

Aqui está um exemplo:

Update: you can actually reproduce this error with objects:

 ```html
 <div *ngFor="let value of objs; let i = index">
   <input [ngModel]="objs[i].v" (ngModelChange)="setObj(i, $event)" />
 </div>
 ```

 ```js
 export class OneComponent {
   obj = {v: '0'};
   objs = [this.obj, this.obj, this.obj, this.obj];
 ​
  setObj(i: number, value: string) {
     this.objs[i] = {v: value};
  }
 }
 ```

 The bug is reproducible as long as the trackBy function returns the same value for any two entries in the array. So weird behavior can occur with any duplicate values.

Sugira uma causa

Você é o único que pegou o bug, então talvez você possa sugerir algumas causas potenciais de por que ele está lá. Talvez o bug só aconteça depois que você encontrar um determinado evento, ou talvez só aconteça no celular.

Também não custa explorar a base de código e talvez identificar o que está causando o problema. Então, seu problema será encerrado muito mais rápido e você provavelmente será atribuído ao PR.

Comunicando-se com clientes

Você pode trabalhar como freelancer solo ou talvez seja o desenvolvedor líder de uma pequena equipe. Em ambos os casos, digamos que você seja responsável pela interface com os clientes em um projeto. 

Agora, o estereótipo do programador é que somos maus comunicadores. Somos conhecidos por usar jargões excessivamente técnicos, dizer aos outros o que é e o que não é possível e até mesmo ficar na defensiva quando alguém questiona nossa abordagem.

Então, como podemos mitigar esse estereótipo? Pergunte aos clientes o que eles querem e sempre ouça seus comentários. Veja como fazer isso.

Faça as perguntas certas

Comece certificando-se de que você e o cliente estejam na mesma página:

• Quem é seu público alvo?
• Qual é o objetivo do site?
• Quem é o seu concorrente mais próximo e o que eles estão fazendo certo?

Fazer perguntas também é uma boa maneira de escrever positivamente, principalmente em situações em que você discorda do feedback ou da decisão de um cliente. Fazer perguntas força essa pessoa a apoiar suas próprias reivindicações, em vez de você atacá-la defendendo sua própria posição:

• Você concorda com isso, mesmo que venha com um custo adicional de desempenho?
• Mover o componente nos ajuda a atingir melhor nosso objetivo?
• Ótimo, quem é responsável por manter isso após o lançamento? 
• Você sabe de antemão se o contraste entre essas duas cores atende aos padrões WCAG AA?

As perguntas são muito mais inocentes e promovem a curiosidade sobre a animosidade.

Venda-se

Se você estiver fazendo uma proposta para um cliente em potencial, precisará convencê-lo a contratá-lo. Por que o cliente deve escolher você? É importante especificar o seguinte:

• Quem é você
• O que você faz
• Por que você é um bom ajuste para o trabalho
• Links para trabalhos relevantes que você fez

E quando você conseguir o emprego e precisar redigir um contrato, lembre-se de que não há conteúdo mais intimidador do que um monte de juridiquês. Apesar de ter sido escrito para projetos de design, o Assassino por Contrato pode ser um bom ponto de partida para escrever algo muito mais amigável.

Sua atenção aos detalhes pode ser a diferença entre você e outro desenvolvedor tentando ganhar o mesmo projeto. Na minha experiência, os clientes contratarão com a mesma facilidade um desenvolvedor com o qual acham que gostarão de trabalhar do que aquele que é tecnicamente o mais competente ou experiente para o trabalho.

Escrevendo microcópia

Microcópia é a arte de escrever amigável UI mensagens, como erros. Aposto que houve momentos em que você, como desenvolvedor, teve que escrever mensagens de erro porque elas foram colocadas em segundo plano até o momento do lançamento.

Pode ser por isso que às vezes vemos erros como este:

Error: Unexpected input (Code 693)

Erros são a última coisa com a qual você quer que seus usuários lidem. Mas eles acontecem, e não há nada que possamos fazer sobre isso. Aqui estão algumas dicas para melhorar suas habilidades de microcópia.

Evite jargões técnicos

A maioria das pessoas não sabe o que é um servidor, enquanto 100% dos programadores sabem. É por isso que não é incomum ver termos incomuns escritos em uma mensagem de erro, como API ou "execução de tempo limite".

A menos que você esteja lidando com um cliente técnico ou base de usuários, é provável que a maioria de seus usuários não tenha feito um curso de ciência da computação e não saiba como a Internet funciona e por que uma determinada coisa não funciona. Daí o erro.

Portanto, uma boa mensagem de erro não deve explicar porque algo deu errado, porque tais explicações podem exigir o uso de termos técnicos assustadores. É por isso que é muito importante evitar o uso de jargões técnicos.

Nunca culpe o usuário

Imagine isso: estou tentando fazer login na sua plataforma. Então eu abro meu navegador, visito seu site e insiro meus dados. Então me dizem: “Seu e-mail/senha está incorreto”.

Mesmo que pareça dramático pensar que esta mensagem é hostil, subconscientemente me faz sentir estúpido. A Microcopy diz que nunca é bom culpar o usuário. Tente alterar sua mensagem para algo menos pontiagudo, como este exemplo adaptado do login do Mailchimp: “Desculpe, essa combinação de e-mail-senha não está correta. Podemos ajudá-lo a recuperar sua conta.”

Eu também gostaria de acrescentar a importância de evitar TODAS AS MAIÚSCULAS e pontos de exclamação! Claro, eles podem ser usados ​​para transmitir emoção, mas na microcópia eles criam uma sensação de hostilidade em relação ao usuário.

Não sobrecarregue o usuário

Usar humor em sua microcópia é uma boa ideia! Pode aliviar o clima e é uma maneira fácil de conter a negatividade causada até mesmo pelos piores erros.

Mas se você não usar perfeitamente, pode parecer condescendente e ofensivo para o usuário. Isso é apenas um big risco a tomar.

Mailchimp diz bem:

[D]não saia do seu caminho para fazer uma piada – o humor forçado pode ser pior do que nenhum. Se você não tiver certeza, mantenha uma cara séria.

(Ênfase minha)

Escrevendo marcação acessível

Poderíamos facilmente gastar um artigo inteiro sobre acessibilidade e como ela se relaciona com a redação técnica. Caramba, a acessibilidade é frequentemente incluída em guias de estilo de conteúdo, incluindo aqueles para Microsoft e Mailchimp.

Você é um desenvolvedor e provavelmente já sabe muito sobre acessibilidade. Você pode até ser um dos desenvolvedores mais diligentes que torna a acessibilidade uma parte essencial do seu fluxo de trabalho. Ainda assim, é incrível a frequência com que as considerações de acessibilidade são colocadas em segundo plano, não importa o quão importante todos sabemos que é tornar acessíveis experiências on-line que incluam todas as habilidades.

Então, se você estiver implementando direitos autorais de outra pessoa em seu código, escrevendo documentação para outros desenvolvedores ou até mesmo escrevendo UI copie você mesmo, esteja atento a algumas práticas recomendadas fundamentais de acessibilidade, pois elas complementam todos os outros conselhos para redação técnica.

Coisas como:

Andy Bell oferece alguns relativamente pequenas coisas que você pode fazer para tornar o conteúdo mais acessível, e vale a pena dar uma olhada neles. E, apenas por diversão, John Rhea mostra alguns truques legais de edição que são possíveis quando trabalhamos com elementos HTML semânticos.

Conclusão

Essas foram seis maneiras que demonstram como a escrita técnica e o desenvolvimento coincidem. Embora os exemplos e conselhos possam não ser ciência de foguetes, espero que você os tenha achado úteis, seja colaborando com outros desenvolvedores, mantendo seu próprio trabalho, tendo que escrever sua própria cópia em um piscar de olhos ou até mesmo redigindo uma proposta de projeto, entre outros coisas.

Conclusão: aprimorar suas habilidades de escrita e colocar um pouco de esforço extra em sua escrita pode realmente torná-lo um desenvolvedor melhor.

Recursos de redação técnica

Se você estiver interessado em redação técnica:

Se você estiver interessado em redação:

Se você estiver interessado em microcópia:

Se você estiver interessado em usar um guia de estilo profissional para melhorar sua escrita:

Se você estiver interessado em escrever para acessibilidade: