DX: Developer Experience em Design Systems
DX, ou Developer Experience, é uma disciplina que descreve a experiência de uma pessoa desenvolvedora ao utilizar um produto. De forma análoga à UX (User Experience), uma boa DX faz toda a diferença na aceitação e no potencial de divulgação do seu produto, seja ele uma API, uma biblioteca, uma ferramenta ou um serviço. A conscientização sobre esse assunto tem crescido tanto que já existe até trabalho especializado — a bio do Twitter da dev Sarah Drasner diz "Head of DX @ Netlify".
Na minha experiência desenvolvendo o Astro, design system da Magnetis, a qualidade da DX é bastante relevante para impulsionar a produtividade do cliente interno. Essas pessoas podem ou não ser colaboradoras da Magnetis, uma vez que o Astro é open source — o que significa que a responsabilidade é ainda maior.
Com base nesse aprendizado, trago alguns pontos de atenção para melhorar a DX do seu projeto:
1. Documentação
Parece até um pouco óbvio mencionar a documentação como um ponto principal de atenção na DX; mas, para um texto que muitas vezes será a única via de comunicação com a pessoa usuária, ele raramente recebe a atenção que merece.
Em projetos e repositórios abertos ou fechados, alguns mantenedores esperam que os usuários entendam tudo apenas lendo o código — o que não só é uma comunicação ruim, mas também uma falha de empatia. E dentro de times, a solução para projetos mal documentados muitas vezes é perguntar pra alguém, o que também é ruim para ambos os lados.
A documentação é sua oportunidade de explicar com linguagem humana a finalidade e a forma de uso do seu projeto. Aqui, você deve ensinar a usar o design system, mas também a contribuir para o código dele (ainda que não seja open source, novas pessoas podem vir trabalhar no projeto a qualquer momento). Pense nesses momentos separadamente — você pode até criar dois arquivos separados no GitHub, como fizemos no repositório do Astro com "Readme" (guia de uso) e "Contributing" (guia de contribuição).
Não entrarei em detalhes sobre como escrever uma boa documentação porque já escrevi um artigo sobre isso, mas, em resumo, ela deve contemplar esses três A's:
- Abrangente: Certifique-se de que o documento cobre todas as dúvidas que possam surgir sobre como funciona o projeto. Explique o que ele faz, como instalar, como usar, e inclua soluções de problemas conhecidos. Seu objetivo aqui é anular a necessidade de te contatar diretamente pra tirar dúvidas. Não seja um gargalo. A fonte da verdade (Single Source of Truth) deve ser a documentação, e não você.
- Acessível: Não assuma que toda pessoa que ler o documento tem o mesmo nível técnico que você, mesmo que você ache que tem um nível técnico baixo (alô, síndrome do impostor!). Evite termos técnicos quando possível. Escreva tutoriais passo a passo. Não assuma que a pessoa sabe clonar um projeto ou instalar dependências via terminal, por exemplo. Explique para um iniciante e você estará explicando para todo mundo.
- Amigável: Ler documentação pode ser uma atividade maçante, então tente não deixá-la desnecessariamente longa. Existe uma diferença entre abrangente e prolixo. Vá direto ao ponto, use um tom amigável e, se quiser, pode até incluir um toque de humor.
2. Padrões de uso
No caso do Astro, o design system é utilizado aplicando classes CSS a uma estrutura de markup exemplificada na documentação. Eis um exemplo abaixo:
Tentamos criar nomes de classes que sejam descritivos para humanos, em vez de algo como a-bt--ur__md1
, ainda que fiquem mais longos; queremos que sejam auto explicativos e memoráveis, o que diminui a confusão e a necessidade de consultar a documentação repetidamente.
Outro ponto importante é que os nomes de classe precisam ser mais específicos (como a-btn
) em vez de totalmente genéricos (como btn
) para evitar conflitos com o CSS existente em projetos legados. O objetivo aqui é gerar o mínimo de efeitos colaterais na importação do design system, e deve-se aplicar essa mentalidade a todos os pontos do projeto que se possa identificar.
Por fim, para criar um sistema escalável e previsível, é preciso tentar manter um padrão de uso que faça sentido. Esse é um grande desafio quando recebemos demandas de design que fogem à norma, e pode ser necessário negociar para satisfazer essas demandas enquanto se mantém também a consistência.
Por exemplo: no Astro, temos muitas variantes de estilos de botões e cada uma delas tem quatro cores. O design system tende a escalar, e, quando introduzirmos novas cores ou estilos, queremos seguir o padrão e até tentar facilitar a manipulação desses botões com menos consultas à documentação.
Para isso, criamos uma estrutura de classes que variam de forma previsível. a-btn--uranus
é o botão primário na cor azul (que nomeamos "uranus"). Nas outras variantes, acrescentamos um modificador que pode ser a-btn--outline-uranus
para o botão outline ou a-btn--ghost-uranus
para o botão ghost.
Além disso, a cor "uranus" pode ser trocada por qualquer uma das outras variantes ("mars" pra vermelho, "venus" pra rosa ou "earth" pra verde) em qualquer um dos botões, que o resultado é previsível.
E para definir o tamanho, acrescentamos obrigatoriamente uma das três classes de tamanho: a-btn--small
, a-btn--medium
ou a-btn--large
. Independente de qual for o botão, o resultado é sempre o mesmo.
Eis um vídeo demonstrando a troca desses modificadores (abra em uma nova aba):
Criando padrões e previsibilidade, o uso fica mais intuitivo, à prova de erros e diminui a dependência da documentação.
3. Tecnologias
Além dos pontos que cobrimos, nos critérios de uma boa DX ainda pesam as consequências das decisões técnicas, como a facilidade de uso, o peso do pacote e as barreiras para utilizar e contribuir.
Tente prezar pela simplicidade pura e evitar complexidade desnecessária. Às vezes, precisamos mesmo de novas ferramentas para escalar o projeto. Mas não deixe de questionar se aquilo é mesmo necessário. Por exemplo, se for possível escrever CSS sem nenhum framework, escreva — é mais viável do que parece. Cada camada que acrescentamos na stack, ainda que nos pareça familiar, pode criar uma barreira para quem não tiver contexto daquela tecnologia específica. É uma questão de empatia e inclusão, mas também de permitir que mais pessoas se agreguem ao seu projeto, usando ou contribuindo.
Faça o seu melhor para não lotar seu projeto de dependências. Cada uma delas requer atualizações no futuro, o que pode quebrar o projeto e gerar trabalho para adaptá-lo, além de ser uma potencial porta para vulnerabilidades. Não perca o controle.
Continue tentando automatizar todos os processos manuais que você conseguir. Por exemplo, em vez de pedir para importar fontes tipográficas ou ícones manualmente, inclua-os no pacote do projeto e crie formas simples de chamar esses assets. Tente aplicar o conceito de "zero configuração".
Teste a velocidade para baixar e rodar o projeto, e busque melhorias nesse processo também.
Em resumo, um design system (ou qualquer projeto) com uma boa DX é um sistema fácil e agradável de usar e de contribuir. Com partes iguais de qualidade técnica e comunicação clara, é possível criar uma experiência que gere menos stress e facilite a vida de desenvolvedores no seu time, e até de outros times por aí afora.
Update em 28/9/19: Escreva um Guia de Atualização quando houver breaking changes
Recentemente, o Astro lançou a versão 2.0.0 com breaking changes — isso é, com alterações incompatíveis que podem causar quebras nos projetos em que a dependência está instalada. Nesse caso, o motivo é que mudamos algumas classes CSS e o nome de alguns ícones.
Atualizar uma dependência nessas condições requer atentas adequações no projeto para evitar surpresas desagradáveis. O que você pode fazer para melhorar a DX?
- Tenha sempre consciência de alterações que podem causar quebras e pese os benefícios antes de prosseguir. Planeje a nova versão de modo a isolar a incompatibilidade e causar o mínimo de efeitos colaterais;
- Quando lançar essa versão (que será major, segundo o Semantic Versioning), escreva um Guia de Atualização mapeando todas as alterações que os desenvolvedores precisam fazer em seus projetos que utilizam o design system. Veja o Update Guide da v2.0.0 do Astro aqui como um exemplo.