💽 👩🏻‍🤝‍👨🏿 👩🏾‍🤝‍👨🏿 Como fazer uma tarefa técnica simples e não perder dinheiro e nervos 🦖 ☹️ 🔭

Olá Habr! Estou abordando este artigo para mim mesmo mais jovem e inexperiente, bem como para qualquer pessoa que não tenha certeza sobre a abordagem da documentação técnica. Embora se ela ajudar alguém do bisonte do ramo de design, ficarei duplamente feliz.

Existem muitos padrões e especificações para a elaboração da TK , mas se os jovens estúdios, enquanto desenvolvem uma simples loja on-line, tentarem cumpri-los, eles não terão tempo para implementar alguns projetos, pois vão à falência, se metendo em vários documentos incompreensíveis.

O que era antes

Somos uma pequena empresa regional envolvida no desenvolvimento personalizado da web que, como muitas outras, no início assumiu projetos, sem realmente saber como fazê-los. Mas esse "crescimento forçado" teve um efeito extremamente positivo sobre os membros da equipe, graças a um grande desejo de se desenvolver, e ajudou a impulsionar as habilidades e a cabeça. O desenvolvimento estava melhorando, mas os termos de referência continuavam no nível mais baixo. Como a maioria dos estúdios para iniciantes, usamos a abordagem descritiva usual do TK: quais páginas, o que deve ser exibido, alguns pontos técnicos, e isso é tudo, talvez.

Em muitos projetos, isso resultou nos seguintes problemas:

A aparência é descrita, mas não o princípio de operação. Um exemplo simples com um carrinho de compras online. Na declaração de trabalho, o botão "Fazer um pedido" foi escrito. Mas o que deve acontecer quando o usuário clica neste botão? Por quais regras o número do pedido é formado? Qual status é atribuído a ele? Para onde está indo o encaminhamento? E se uma das mercadorias estiver esgotada enquanto o usuário fizer um pedido? Não houve respostas para essas e muitas outras perguntas no ToR, mas esse é apenas um pequeno elemento. Esses momentos não descritos levaram a disputas com o Cliente, uma forte saída do orçamento e outras conseqüências desagradáveis.
Falta de blocos reutilizáveis. Muitos sites têm os mesmos blocos usados em locais diferentes, por exemplo, visualizações de produtos. Mas esse bloco, como resultado, foi descrito em cada página. Isso é muito ruim por vários motivos. Em primeiro lugar, se necessário, as alterações devem ser feitas em vários locais ao mesmo tempo, você pode perder algo e haverá uma discrepância. Em segundo lugar, mesmo com os mesmos elementos na visualização, o cliente pode exigir que sejam feitos de maneira diferente, o que implica custos adicionais.
TK não se correlaciona com tarefas para a equipe. Quanto mais longe a formulação do problema da realidade, menor será a qualidade da produção. Este é outro problema que eu queria resolver.

Nova abordagem

Tendo determinado as metas, desenvolvemos um novo conceito, bastante simples, mas eficaz.

TK consiste nas seguintes seções:

1. Introdução
Estática
Dynamics
As tarefas
Painel do administrador
Requisitos técnicos gerais

De projeto para projeto, a composição dessas seções pode variar, mas a estrutura básica permanece. Vamos dar uma olhada.

Introdução e preparação para implementação

Descrevemos brevemente o projeto, seus objetivos, CA, deixam links para a análise pré-projeto.
Descrevemos o processo de inicialização do projeto: configuração do ambiente para desenvolvedores e a abordagem para o desenvolvimento de um conceito de design para designers.
Os princípios de adaptabilidade ou controle de versão. Recentemente, em nosso trabalho, aderimos ao seguinte princípio - “adapte tudo o que se adapta”. Em outras palavras, no início do trabalho no TK, entendemos que funcionalidade complexa precisamos (ou pode ser necessária em um futuro próximo) e, juntamente com o designer e desenvolvedor front-end, apresentamos maneiras de adaptá-la. Com a nova abordagem, não houve resultados negativos, portanto, versões separadas não precisaram ser descritas.

Esta seção tem como objetivo atualizar a equipe e preparar o terreno para o desenvolvimento imediato do projeto.

Estática

Como todos sabemos, as páginas podem conter informações estáticas ou dinâmicas enviadas do servidor. Subseções estáticas - páginas do projeto. Dividimos cada página em blocos. Se o bloco for estático, descreveremos sua essência e tipo de conteúdo. Por exemplo, uma descrição de um dos blocos na página Sobre a empresa pode ser assim. “As principais vantagens da empresa. 5-6 ícones descritivos. ” Esta é uma descrição muito breve, mas suficiente para uma avaliação precisa do bloco. Ao descrever estática, o objetivo principal é definir uma estrutura clara. Criar ícones adaptáveis não é difícil, mas com um gráfico ou tabela, tudo não é tão simples e inequívoco. Mas, ao mesmo tempo, não importa que tipo de ícones e assinaturas haverá.

Se a página contiver um bloco que possa ser "colocado entre colchetes", no lugar de sua integração, escreveremos "A funcionalidade NAME está sendo integrada e a funcionalidade em si é descrita na seção Dynamics.

Além das páginas, o Statics inclui uma descrição de pop-up e letras. Na minha opinião, não faz sentido colocá-los em uma seção grande separada e inflar a estrutura.

Dynamics

Tudo o que se relaciona com a dinâmica que chamamos de funcional. Talvez alguma outra divisão apareça mais tarde, porque Já aqui vários tipos de tarefas pertencem:

Bloquear Fazemos a dinâmica:
- Blocos usados em diferentes partes do site.
- Blocos que fazem sentido para avaliar separadamente. Em primeiro lugar, simplifica o próprio processo de avaliação e o entendimento do cliente sobre a complexidade de um elemento individual. Em segundo lugar, os blocos que não são vitais para um projeto geralmente se enquadram nessa categoria e, com essa abordagem, é mais fácil excluí-los do orçamento.
- Os processos que ocorrem durante uma ação específica do usuário. Antes de tudo, isso inclui as ações que ocorrem ao fazer um pedido, pagar, adicionar à cesta, etc. Essa funcionalidade durante o desenvolvimento do projeto geralmente é finalizada e, portanto, essas melhorias são muito mais convenientes para descrever.
- Integração de serviços de terceiros. Dependendo da complexidade da integração, ela pode ser descrita como uma funcional ou vice-versa dividida em várias diferentes para descrever consultas individuais.

As tarefas

Esta seção é usada para trabalhos que não podem ser atribuídos a nenhuma das outras seções: desenhe um banner, defina um contador métrico, analise mercadorias, etc.

Painel do administrador

Aqui descrevemos a estrutura, modelos e campos. O detalhamento é dividido em seções, por exemplo, "Produtos", "Catálogo", "Pedidos" etc. Descrevemos que diferentes funções de usuário podem visualizar o que editar.

Requisitos técnicos gerais

Inclui algumas subseções, nem todas realmente requisitos técnicos, mas novamente não fazia sentido separá-las:

Requisitos de tag e micro marcação de SEO
Regras de transliteração
Teste manual e automático
Navegadores suportados
...

Novas versões

Ao descrever novas versões, é necessário fazer alterações nos elementos existentes. Consideramos as seguintes maneiras de descrever as melhorias: no início de cada uma das seções (Estática, Dinâmica, AP), escreva "Melhoria da funcionalidade" NOME "ou crie uma seção separada" Melhorias ", na qual todas as tarefas de alteração serão descartadas de uma só vez. Até o momento, optamos pela segunda opção, mas isso está relacionado à conveniência em projetos específicos. Em outras condições, o primeiro método é melhor.

Depois de escrever as especificações técnicas para a nova versão, as fundimos em uma para que a próxima possa ser escrita com base em um documento.

Exemplo

Para maior clareza, vamos analisar a estrutura do TK com base em uma página simplificada na seção de catálogo.

Estática

Página Seção de Diretório

Usado para exibir mercadorias pertencentes a uma seção do catálogo de qualquer nível, exceto a raiz.

A seguinte funcionalidade está integrada:

“Pão ralado”
"Árvore de diretórios"
“Filtragem. Disposições Gerais ”
“Filtragem. Texto "
“Filtragem. Texto e imagem ”
“Filtragem. Range ”
“Classificar. Por padrão "
“Classificar. Preços crescentes "
“Classificar. Preço decrescente ”
“Visualização do produto. Lado a lado "
“Paginação. Página
"Bloco de texto". Integra-se como um bloco de texto SEO em frente ao porão

URL: / c / 1745-name, em que 1745 é o ID da categoria de diretório atual e name é o nome transliterado dessa categoria.

Dynamics

Como a página contém muitas integrações, darei exemplos para as duas mais interessantes.

Funcionalidade “Filtragem. Disposições Gerais ”

Externamente, a filtragem é uma série (ou várias linhas) de botões com o nome do filtro. Quando você clica no botão, uma lista suspensa é aberta com caixas de seleção com valores de filtro (valores das características correspondentes do produto). A largura da lista suspensa depende do tamanho máximo do valor nesta lista. Na área visível da lista suspensa, não são exibidos mais de 10 itens. Se houver mais valores de filtro, uma barra de rolagem será exibida. Abaixo dos valores do filtro está o botão Aplicar. Se pelo menos um valor estiver selecionado e o usuário clicar no botão Aplicar, fora da área de filtro ou no botão com o nome do filtro, então:

a lista suspensa fecha e o filtro é aplicado. Apenas os produtos que correspondem aos filtros ativos atuais permanecem na seção atual
o nome do botão de filtro assume a forma: "Nome do filtro: K", em que K é o número de valores de filtro selecionados, se houver 2 ou mais, ou "Nome do filtro: valor", se um valor foi selecionado.
a cor do botão de filtro muda para o tipo de filtro usado
nos valores de outros filtros, apenas as opções que satisfazem os filtros ativos no momento permanecem. Se um valor permanecer em um dos filtros inativos, seu botão se tornará inativo e o nome será exibido no formato "Nome do filtro: valor"
para todos os filtros ativos, uma cruz é adicionada após o nome, quando clicado, somente esse filtro é redefinido
paginação é redefinida

Se pelo menos um filtro estiver ativo, depois de todos os botões com filtros, o botão "redefinir filtros" aparece, quando clicado, o valor de todos os filtros é redefinido.

Ao alternar da categoria atual para outra, é feita uma verificação da coincidência dos filtros ativos e dos valores selecionados neles com os filtros correspondentes e os valores da categoria para a qual a transição foi feita. Na categoria recém-selecionada, os filtros e os valores selecionados neles iguais permanecem ativos.

A filtragem pode ser integrada de duas maneiras: dinâmica e estaticamente. A integração dinâmica permite definir a característica pela qual a filtragem é executada no painel administrativo. Tais integrações são indicadas sem parâmetros adicionais. A integração estática é aplicada à página por padrão. Ao descrever a integração, um parâmetro adicional é indicado - a característica pela qual a filtragem é realizada.

Os filtros selecionados são adicionados à URL por meio de parâmetros de consulta.

Funcionalidade “Visualização do produto. Lado a lado "

É um bloco (retângulo) com as informações mais importantes do produto para o usuário. Na versão lado a lado, as principais informações são a imagem do produto. A visualização contém:

Preço (número inteiro em rublos russos)
Nome do produto
Rotule "Na loja" ou "Na janela"
Imagem
Tamanho
Botão "Ao carrinho" (integração da funcionalidade "Adicionar ao carrinho")
Botão "Adicionar aos Favoritos" (Integração da funcionalidade "Adicionar aos Favoritos")

Ao clicar em qualquer área da visualização, além do botão "Adicionar ao carrinho", você será direcionado para a página do produto.

Em uma linha deve ser colocado 3-4 peças com visualizações do produto.

Como você pode ver, outra função está integrada a essa funcionalidade, o que permite fazer partições muito convenientes. Por exemplo, “Adicionar ao carrinho” e “Adicionar aos favoritos” também são usados no mapa do produto.

Painel do administrador

Uma página requer um grande número de seções do AP, descreverei uma delas.

Produto

Lista de todos os produtos com filtragem. Ao editar / adicionar um item, os seguintes campos estão disponíveis:

Título (texto)
Marca (rádio)
Imagens
Preço (inteiro)
Descrição (bloco de texto)
Tipo (loja / vitrine, rádio)
Condição. O significado inclui Título (texto) e Explicação (texto).
Status As opções são:
1. à venda
2. com moderação
3. em revisão
4. rejeitado
5. esgotado
6. falha na verificação
7. cancelado pelo vendedor
Tamanho da etiqueta (opcional). Campo de texto sem validação
...

Existem mais de 30 campos e, para não inflar o artigo, os omitimos.

Conclusões

Vantagens da nova abordagem:

Completude . Este TK permite que você descreva claramente os requisitos, que é o parâmetro principal e necessário de qualquer TK.
Clareza . Cerca de metade dos nossos clientes não tem um especialista técnico do seu lado e enfrenta o desenvolvimento pela primeira vez. Portanto, era muito importante tornar o TK o mais claro e legível possível. E nós conseguimos! Mesmo os clientes mais experientes em tecnologia não entendem como funciona, eles podem lê-lo facilmente e fornecer um excelente feedback.
Molecularidade A TK está em total conformidade com nossos requisitos para dividir em elementos individuais, o que simplifica e resolve os problemas descritos acima. Os blocos TK correspondem diretamente às tarefas que são executadas pelos desenvolvedores, as quais foram satisfeitas. O TK também se encaixa perfeitamente no sistema de design (um artigo sobre ele será lançado na próxima semana).
Facilidade de estimativa e configuração de custos . Tarefas bem descritas e quebradas tornaram-se simples e agradáveis de avaliar. Se, durante a avaliação, entendermos que os requisitos estão incompletos, então os adicionamos. Para cada projeto (estágio), criamos uma tabela do Google na qual o cliente pode experimentar diferentes configurações do projeto e determinar a opção mais adequada para ele por preço / funcionalidade.
A interação com o cliente subiu para um novo nível . As alterações feitas permitem definir claramente os limites do projeto. Se forem necessárias alterações em relação à CT, isso é avaliado como uma nova tarefa, embora com a abordagem antiga isso tenha causado muita controvérsia.
Rentabilidade . Porque este é basicamente um negócio, esse indicador, juntamente com o anterior, é um dos mais importantes. Um estudo detalhado permitiu minimizar o número de tarefas mal avaliadas. Nenhum dos projetos implementados sob a nova abordagem teve um excesso de orçamento.

Contras:

Fazendo melhorias . Em um dos projetos, foi necessário introduzir o status das mercadorias. Como resultado, um grande número de melhorias de 2 a 3 linhas acabou. Isso não pode ser chamado de menos claro, porque a integridade dos requisitos é uma prioridade, mas a abordagem ideal de dados não pode ser chamada.
A complexidade da percepção na automação dos processos de negócios . Se você toma os processos de negócios de algumas empresas desde o momento da venda até o recebimento das mercadorias pelo comprador, nem sempre existe a possibilidade (ou a necessidade nos primeiros estágios) de cobrir todo o processo às custas da Statics, Dynamics e AP, porque muitas tarefas são realizadas manualmente, discutidas com os clientes por telefone etc. Isso complica um pouco a percepção de TK em sua forma pura e requer uma descrição adicional dos processos.
Custo e tempo de desenvolvimento . A venda de TK, é claro, tornou-se mais difícil, porque nem todos no primeiro contato com o desenvolvimento estão dispostos a pagar de 10 a 20% do projeto, enquanto muitos de nossos concorrentes cobram de 10 a 20 mil por isso, mas esse trabalho vale a pena durante a implementação, reduzindo riscos do projeto e melhoria da qualidade.

As vantagens da nova abordagem tiveram um efeito muito positivo em todos os aspectos do nosso trabalho e ajudaram a identificar pontos fracos aos quais não tínhamos prestado atenção antes. Contras, embora existam, são insignificantes, especialmente em comparação com os profissionais.
Cada projeto traz algo novo, aprimora os cantos e permite que você altere para melhor.

Estamos tão satisfeitos com o resultado que decidimos abandonar os rastreadores de tarefas padrão em favor da finalização do Google Docs para trabalhar totalmente com tarefas baseadas no TK. Se o experimento for bem-sucedido, escreveremos um artigo separado sobre ele. Enquanto isso, aguardamos críticas e conselhos objetivos de você, com a esperança de que este artigo tenha ajudado alguém).

Como fazer uma tarefa técnica simples e não perder dinheiro e nervos