ux-design-for-architects
Diretriz para arquitetos projetarem e revisarem a UX de pontos de contato do usuário que não são UI (APIs / Configuração / Extensões). O design de telas de UI (cores, layout, etc.) está fora do escopo.
UX não se limita à UI; ela abrange todos os pontos de contato entre o sistema e o usuário. Uma UX ruim em um ponto de contato é difícil de mudar depois (porque os usuários dependem dela) e reduz a probabilidade de sucesso de todo o sistema. Por isso, decida antes da implementação.
Como proceder
- Identifique o ponto de contato: Pode ser API / Configuração / Extensão (múltiplos são permitidos).
- Identifique o usuário (Princípio 1): Quem, para quê, com qual nível técnico.
- Leia o guia detalhado do ponto de contato relevante:
- Configuração →
references/configuration.md - API →
references/api.md - Extensões →
references/extensions.md
- Configuração →
- Verifique com os 6 princípios (abaixo). Se estiver propondo um design, acrescente uma justificativa baseada nos princípios.
- Se for uma revisão, aponte os problemas no formato de
references/review-checklist.md. - Para pontos controversos, confirme com o usuário, incluindo uma hipótese (AskUserQuestion).
Os 6 princípios de UX
| # | Princípio | Essência | Por quê |
|---|---|---|---|
| 1 | Entenda o usuário | Entenda objetivos, nível técnico, modelo mental e fluxo de trabalho típico; faça o sistema se comportar como esperado (princípio da menor surpresa) | Os usuários agem de forma diferente do esperado. Observar e medir é mais eficaz do que perguntar |
| 2 | Faça o mínimo necessário | Ofereça apenas os recursos necessários. Adote padrões amplamente utilizados (OAuth, OpenID, etc.) quando existirem | Tudo que é fornecido vira dívida. Uma vez lançado, os usuários se acostumam e é difícil de mudar |
| 3 | Torne o manual desnecessário | Torne o uso óbvio; guie com recomendações e pistas | Usuários não leem manuais. Se não conseguem resolver, julgam que o produto é ruim |
| 4 | Pense em termos de troca de informações | Evitar perguntar > perguntar menos > perguntar de forma fácil de responder. Nunca pergunte a mesma coisa duas vezes | Entrada de dados é um fardo. É possível reduzir por inferência, memória ou derivação |
| 5 | Mantenha o simples simples | Remova barreiras das primeiras operações. Forneça clientes pré-configurados e exemplos | Iniciantes desistem mais facilmente. A primeira experiência determina o engajamento |
| 6 | Projete a UX antes da implementação | Projete a UX antes da arquitetura, refinando com feedback | Mudar a UX após a implementação é caro. Atraso a implementação, aprofunde o design |
Decidindo quando perguntar (detalhamento do Princípio 4)
Pense em ordem de prioridade:
- Não pergunte: Valores padrão razoáveis, detecção automática do ambiente, memória de entradas anteriores, derivação de informações conhecidas
- Pergunte menos: Apenas o que é realmente necessário
- Pergunte de forma fácil de responder: Não use termos da implementação interna; pergunte de forma que o usuário possa responder sem fazer cálculos mentais. Exemplo: em vez de "número máximo de entradas de cache", pergunte "limite de memória para o cache"; ou ainda, derive detalhes a partir de uma escolha de modo, como "servidor ou cliente?"
Ao retornar saída/resposta (Princípio 4)
Se não houver problemas de desempenho, retorne informações suficientes para que o usuário entenda e possa prever o próximo passo. Se o resultado de uma chamada for passado para a próxima, permita que seja passado com o mínimo de transformação.
Resumo por ponto de contato
- Configuração: O melhor é "não adicionar configuração". Em segundo lugar, determinar automaticamente. Por último, adicionar com um valor padrão razoável. A pergunta é: "O usuário tem um contexto melhor do que nós?" — Só crie uma configuração se a resposta for Sim. Não silencie erros como chaves desconhecidas ou falhas de aplicação; retorne erro. Valores de configuração válidos devem ser verificáveis na inicialização.
- API: Os usuários são desenvolvedores. Deve ser fácil de aprender, difícil de usar incorretamente, e o próximo passo deve ser sempre claro. Faça uma coisa bem feita. Não force o usuário a escrever código repetitivo. Siga padrões. Versionamento desde o início. Adie a publicação até que seja necessária; primeiro use internamente.
- Extensões: Espere até compreender profundamente o caso de uso (é possível adicionar depois com refatoração). Faça uma coisa bem feita. Defina entradas e saídas; não exponha a estrutura interna. Depois de publicar, é difícil de mudar.
Falhas comuns (suspeite durante design/revisão)
- Falta de conhecimento especializado em UX / atraso na contratação de especialistas
- Foco apenas na UI, negligenciando a UX de APIs, configuração e extensões
- Líder técnico decide a UX e só pede ao especialista ajustes finos na UI
- Ignorar as sugestões do especialista
- Ficar em dúvida entre duas opções e criar uma configuração para escapar (transferindo o problema para o usuário)
Se não houver especialista, declare isso explicitamente e recomende envolver um especialista em UX no início. No entanto, não pare o design por recusar conselhos; apresente uma proposta provisória seguindo este guia.
Conexão com abordagens iterativas
- Derive o design da jornada do usuário → Aplique este guia a cada ponto de contato na jornada
- Fatia iterativa → Crie apenas os pontos de contato necessários na primeira fatia (APIs públicas e extensões geralmente podem vir depois do MVP)
- Itens difíceis de mudar: projete profundamente, implemente lentamente → UX é um exemplo clássico. Aprenda observando o uso real
Formato de saída
Proposta de design: "Ponto de contato → Perfil do usuário → Proposta → Princípio relevante e motivo → Pontos não resolvidos" de forma concisa.
Revisão: Use o formato de references/review-checklist.md.