Há alguns meses, completei uma das etapas da minha carreira profissional como Shiva com vários braços em uma startup no desenvolvimento de um sistema de gerenciamento de laboratório de testes não destrutivo. Vou lhe contar como consegui documentar uma parte do desenvolvimento relacionado à conexão e geração de documentos em volume suficiente para o uso silencioso do sistema criado por dois anos.
Vou tentar fornecer ao leitor material útil o máximo possível e, ao mesmo tempo, observar os interesses do projeto e não divulgar as nuances da implementação e uso interno.
Dado:
- equipe de desenvolvimento legal e, claro, o gerente de projeto. Na época do início do projeto, eu trabalhava como diretor de arte em um dos estúdios de Tomsk e acabei na equipe de startups.
- start-up com datas de concreto armado para um evento específico - início de aceleração no FRII
- conjunto inicial de modelos de mais de 15 documentos de vários tamanhos, de 1 página a mais de 100 páginas em um documento com diferentes condições de conexão
- projeto de terceiros que deve ser integrado a uma solução futura
- designer (analista, designer, designer, diretor de arte, proprietário do produto, gerente de produto, tudo em um)
Desafio:
- iniciar um projeto no prazo
- não morra equipe seis meses depois no caos ao conectar novas funcionalidades e ainda mais documentação no sistema (em caso de conclusão bem-sucedida da aceleração)
- com o número mínimo de cartas e esforços despendidos para obter a documentação adequada
- alienação da documentação para qualquer equipe / funcionário que não esteja em contexto
Devo dizer imediatamente que os seguintes modelos de documentos foram feitos sem nenhuma metodologia, fui guiado apenas pelas especificidades do projeto, bom senso e um terrível limite de tempo.
Análise e preparação
Espero que você comece qualquer tarefa não trivial analisando o material; no meu caso, o material era modelos de documentos e um projeto existente com o qual a integração era necessária. Mas então estamos falando apenas de documentos. Eu precisava determinar a frequência de uso do mesmo tipo de dados no mesmo documento e entre documentos. Era necessário entender se é necessário um sistema agora ou se você pode fazê-lo rapidamente no joelho primeiro e depois lidar com o resultado. Naquele momento, foi decidido que o sistema era necessário, pois quase todos os dados, em um volume ou outro, eram repetidos dentro de um documento e em todo o pacote de documentos - e este é um sinal claro de confusão já no segundo ou terceiro documento ao se conectar.
O próximo passo é entender o estado de limpeza da marcação dos documentos. Eu vou explicar O fato é que recebi modelos de documentos já preenchidos do metodologista - quem, quando e como os fiz, esses documentos não sabiam, mesmo sabendo que isso daria pouco. O documento .docx dentro é algo como xml para texto e alguns elementos podem não estar visíveis visualmente em um documento aberto, mas estar presentes na marcação do documento. Não se sabe como o gerador de documentos e o software para visualização do documento reagirão a esses elementos de marcação. A aposta principal foi no Microsoft Word, mas existem o OpenOffice, o LibreOffice e todos eles podem dar resultados diferentes. Portanto, todos os modelos passaram pelo processo de limpeza de estilos - uma redefinição completa de qualquer design e redesign com estilos de documentos, em algum lugar com o ajuste da estrutura do documento. E mesmo após esse procedimento, coletamos problemas no conteúdo dos documentos após a geração. No futuro, cheguei à conclusão de que, se o documento for pequeno, é melhor reorganizá-lo do zero e não levar o modelo fornecido pelo metodologista para o trabalho, economizando tempo em documentos de até 5 páginas. Ninguém quer procurar o motivo pelo qual algo ocorreu, o processo de depuração desses casos é extremamente tedioso para a equipe. No mesmo estágio, se você possui um pacote de documentos, chega a uma linguagem visual uniforme.
E como realizamos um ritual de limpeza de documentos, o ovo da páscoa nas meta-informações se sugeriu, porque as pessoas gostam de compartilhar bons documentos
Após todo o trabalho relacionado à preparação dos documentos, procedi à marcação de documentos para geração automática.
Marcação de documentos
Nesse estágio, peça aos desenvolvedores o formato variável que suporta o gerador de documentos selecionado por sua equipe, para que você não precise refazê-lo posteriormente. Eu tive que refazê-lo, mas isso foi devido à substituição do gerador. O novo gerador não pôde trabalhar com as variáveis no formato anterior, mas as capacidades do novo gerador se mostraram mais importantes para nós e decidimos substituí-lo.
Verifique a suficiência das informações no sistema, determine quantos dados não são suficientes para o documento. Quando esses dados devem aparecer no sistema? Se não houver dados suficientes para a auto-suficiência do documento, é melhor adiá-lo. O que é auto-suficiência de documento? No meu caso, havia um documento que concluímos em três estágios, mas ele foi auto-suficiente imediatamente para um cenário específico, mas não abrangeu o restante dos cenários. Por isso, decidimos lançar o documento para produção, deixando células vazias para scripts descobertos para o usuário preencher, e posteriormente finalizou o documento com a aparência da funcionalidade necessária.
Documentação de variável e interface
No começo da nota, escrevi que estávamos estritamente limitados a um evento específico. Além disso, eu já tinha férias planejadas. Quando eu estava indisponível, mas precisava urgentemente adicionar uma variável do sistema (não disponível na interface do usuário final), os desenvolvedores adicionaram a linha à variável e, em seguida, adicionei as condições ausentes. Nesse sentido, a especificação de variáveis não finge ser correta e ideal, mas é um documento de trabalho, que posteriormente se expandiu e evoluiu. A guia principal do documento não mudou estruturalmente desde o início e no momento da minha partida do projeto.
Modelo "
Especificações para esses campos ", que você pode usar e usar no seu trabalho. No documento, deixei parte dos dados como exemplo. Este modelo pode ser adequado para a documentação da interface para controlar a qualidade do desenvolvimento. Por exemplo, o proprietário de um produto sabe qual é o resultado mínimo que ele obterá, o desenvolvedor entende claramente o mínimo a ser feito a partir da descrição da tarefa + das especificações desses campos e, se algo estiver faltando, ele informará sobre isso, o engenheiro de teste verá claramente casos óbvios. No final, tudo está no preto.
A princípio, o documento levará um número significativo de horas, mas economizará muito tempo gasto, e a atualização ocasionalmente levará literalmente minutos.
Conteúdo:
- A página é um guia para uma pessoa fora do contexto do projeto, para onde procurar. Útil para um novo membro de uma equipe ou terceirização de um projeto.
- Nome do campo
- Tipo de campo
- Campo obrigatório em projetos (lembro que tínhamos um banco de dados de outro projeto) - um marcador para sincronizar o requisito de ligação entre o documento e a interface. Se as informações no documento forem vinculativas e o sistema não puder recebê-las de outra maneira, será necessário tornar esse campo obrigatório na interface
- Máscara de campo - o formato para registrar informações é claramente definido na documentação regulatória.
- Valor padrão
- O número máximo de caracteres no campo
- Escalabilidade de campo (depende da resolução) - descrição do comportamento de um elemento da interface, dependendo da resolução
- Requisito de dados - que interação é permitida com o elemento da interface e o que pode surgir
- Amostra bem sucedida
- Espaço reservado - dica de ferramenta para o usuário dentro do elemento da interface
- Personalização do campo - elementos de interface não padrão ou tarefas concluídas
- Informações adicionais ao lado do campo - quando o espaço reservado não pode ser dispensado devido à quantidade de texto, usamos uma dica de ferramenta ou identificador
- Tipo de validação
- Mensagem de validação - condições e resposta do sistema
- Variável nos modelos de documento - o que será inserido no modelo de documento
- Link para a página - não foi usado como resultado
- Localização do campo na interface - não foi usado como resultado
Documentação de conexão de documento
Para receber o documento pelo usuário final, não basta editar e marcá-lo; o documento ainda precisa estar conectado corretamente. É especialmente importante se você tiver o mesmo modelo, dependendo das condições, alterar seu conteúdo. Para isso, usei um documento separado.
Modelo "
Conexão de documento ", espero que seja útil para alguém.
Conteúdo:
- Status - indica o estado atual do documento no sistema. Conectamos um documento em três etapas, o status do documento era "Finalizar"
- Documento - o nome do documento na equipe, na base de conhecimento e no sistema de documentação e configuração de tarefas
- Tipo
- O formato do documento é quando o mesmo documento pode estar em modelos diferentes, dependendo da documentação regulamentar e técnica à qual este documento corresponde
- Formação - um documento pode ser apenas um modelo no qual as variáveis são simplesmente substituídas ou, a partir de um modelo de 3 páginas, você pode obter mais de 100 documentos de página - documentos dinâmicos
- A presença no pacote é um recurso do sistema, você pode obter um pacote de documentos ou fazer download de documentos separadamente
- Condição de presença - a presença de um documento específico na embalagem
- O recurso de conexão é a parte do documento que não está no modelo e é regulamentada pelo código.
- Link para o arquivo para conectar
- Faça o download separadamente
- O nome do arquivo a ser baixado - um documento no sistema pode ser chamado como você quiser, mas o usuário final deve ver um nome específico ao fazer o download
Total
Como resultado, preenchi 362 linhas nos dois documentos. Volume impressionante? Mas, na realidade, são mais de 30 modelos de documentos e um total de 40-60 horas de trabalho de uma pessoa foi gasto em dois anos (1-1,5 semanas), excluindo a edição dos modelos em si e a redação das tarefas de conexão.
O projeto passou com êxito pela aceleração no IIDF e chegou à forma de sua própria equipe de desenvolvimento. Graças à documentação existente, os novos membros da equipe não precisaram se aprofundar no que foi feito antes deles com relação à geração de documentos. Todos os membros da equipe tiveram acesso ao status atual dos documentos conectados a qualquer momento.
As principais etapas da documentação do processo de geração de documentos:
- Análise do conteúdo dos documentos
- Higiene de documentos
- Corrija variáveis em paralelo com a marcação do documento
- Corrija as nuances da conexão de modelos de documento.
Obrigado por chegar ao fim.