Documentação de uma aplicação móvel: lista de entrega do projeto

O que deve existir no pacote de entrega

O objetivo não é receber o maior número possível de ficheiros. É transferir controlo, conhecimento e provas suficientes para outra equipa conseguir trabalhar sem começar uma investigação do zero.

Nem todos estes elementos são documentos. Alguns são contas, permissões, demonstrações ou decisões guardadas numa ferramenta de projeto. O formato pode variar; o essencial é que a informação esteja atualizada, tenha um responsável e possa ser testada.

A entrega começa no início do desenvolvimento

Deixar toda a documentação para a última semana cria um resultado frágil. Nessa altura já se esqueceram decisões antigas, contas temporárias tornaram-se permanentes e ninguém quer reconstruir meses de contexto.

Defina no contrato quais são os materiais de entrega e como serão aceites. A empresa deve ter acesso ao repositório principal, ao espaço de design e às contas críticas durante o desenvolvimento, e não apenas depois do último pagamento. Convém também esclarecer quem é o titular de cada conta, quem paga cada serviço e o que acontece aos acessos quando termina o apoio.

A lista de entrega de projetos da Futurice trata esta fase como um pequeno projeto com responsável, prazo e critérios de aceitação. É uma abordagem sensata: a transferência exige preparação, perguntas e testes, não apenas um envio de ficheiros.

O código deve reproduzir a versão que está nas lojas

Peça os repositórios completos da aplicação, do servidor, do painel de administração e, quando existir, da configuração da infraestrutura. Um ficheiro ZIP pode servir como cópia adicional, mas perde o histórico, as ramificações e as etiquetas que identificam versões publicadas.

O repositório deve incluir instruções curtas e concretas: versões das ferramentas, instalação das dependências, nomes das variáveis de ambiente, arranque local, comandos de testes e passos de publicação. As palavras-passe e chaves privadas não devem aparecer nessas instruções. Devem ser transferidas através de um gestor de palavras-passe ou de contas empresariais.

Faça um teste de compilação limpa. Um programador que não tenha trabalhado no projeto deve seguir apenas a documentação e gerar uma versão funcional num computador preparado de raiz. O guia de entrega de código da Koder recomenda esta verificação porque um repositório que ninguém consegue compilar tem pouco valor operacional.

Registe também qual é a alteração do código e qual é a versão do servidor associada à aplicação publicada. Se a versão da loja foi criada a partir de alterações locais que nunca chegaram ao repositório, essa situação deve ser corrigida antes da aceitação.

Contas, acessos e faturação precisam de responsáveis claros

Crie um inventário dos serviços utilizados. Para cada um, indique finalidade, titular, administrador, contacto de faturação, método de recuperação e data de renovação. Uma aplicação pode depender de:

• Apple Developer, App Store Connect e Google Play Console;
• alojamento, base de dados, armazenamento e distribuição de ficheiros;
• domínio, DNS e correio eletrónico transacional;
• notificações, mapas, SMS e autenticação;
• pagamentos, subscrições e validação de compras;
• análise, relatórios de falhas e apoio ao cliente.

As contas essenciais devem, em regra, pertencer à empresa que é dona do produto. A equipa de desenvolvimento recebe permissões adequadas ao seu trabalho. Uma única conta pessoal partilhada dificulta a saída de colaboradores, a recuperação de acesso e a identificação de alterações.

Transferir uma aplicação entre contas das lojas não é o mesmo que enviar uma palavra-passe. A Apple tem um processo próprio para transferência de aplicações e a Google explica que elementos acompanham a transferência e quais exigem nova configuração. Verifique antecipadamente compras na aplicação, serviços integrados, grupos de teste e permissões.

O design e as decisões também fazem parte do produto

Os ficheiros editáveis no Figma ou noutra ferramenta devem corresponder à versão atual da aplicação. Devem conter componentes, estados, ícones, tipos de letra, regras de exportação e recursos com licença. Imagens exportadas em PNG ajudam na consulta, mas não permitem manter o sistema visual.

Vale a pena preservar um registo curto das decisões que não são evidentes nos ecrãs. Porque é que uma encomenda reserva o stock antes do pagamento? Porque não pode um estafeta alterar um estado concluído? Como é tratado o apagamento da conta? A nova equipa não precisa de ler todas as reuniões, mas precisa de compreender regras que afetam dinheiro, privacidade e apoio.

Entregue ainda a lista de tarefas atual, os erros conhecidos e o trabalho adiado. Separe defeitos confirmados de ideias para o futuro. Indique impacto, solução temporária e razão do adiamento. Uma lista honesta permite planear melhor do que uma apresentação que finge que a primeira versão não tem limitações.

Dados, infraestrutura e recuperação devem ser testados

Um esquema simples da arquitetura deve explicar como a aplicação, o servidor, a base de dados, o armazenamento e os serviços externos comunicam. Identifique os ambientes de desenvolvimento, teste e produção, bem como o caminho usado para promover alterações entre eles.

Na base de dados, documente a origem do esquema, as migrações, as regras de conservação, a exportação e a localização das cópias de segurança. Depois restaure uma cópia num ambiente seguro. Ver uma opção chamada “cópias automáticas” não demonstra que os dados estão completos nem que podem ser recuperados.

A monitorização também deve mudar de mãos. A nova equipa necessita de acesso aos relatórios de falhas, alertas do servidor, pagamentos recusados e indicadores críticos do negócio. Registe quem recebe cada alerta e como esse contacto será atualizado.

Num produto antigo, combine esta análise com uma avaliação de modernização da aplicação e com o planeamento do custo de manutenção. A entrega costuma revelar dependências antigas ou serviços sem responsável que devem ser estabilizados antes de acrescentar funcionalidades.

A publicação não pode depender da memória de uma pessoa

As instruções de lançamento devem indicar a configuração da compilação, a numeração das versões, a assinatura, o canal de teste, as contas de revisão e o procedimento para uma correção urgente. Devem também explicar quando é necessário atualizar textos da loja, declarações de privacidade ou informações de segurança.

Não envie certificados e chaves privadas por correio eletrónico sem proteção. Use um local seguro acordado, limite os acessos e substitua qualquer segredo que tenha sido exposto durante uma transferência informal. No Google Play, distinga a chave de carregamento da chave de assinatura da aplicação. No ecossistema Apple, registe certificados, identificadores, capacidades e funções no App Store Connect.

Peça à equipa anterior para demonstrar uma publicação num canal de teste. Uma gravação curta pode ajudar, mas mantenha instruções escritas como referência principal: os vídeos envelhecem rapidamente quando as interfaces das lojas mudam.

Um teste de aceitação em cinco passos

Em vez de aceitar uma pasta pela aparência, teste tarefas que terão de ser realizadas no dia a dia:

1. Compilar: um programador novo gera uma aplicação funcional num ambiente limpo.
2. Operar: o responsável abre o painel de administração, encontra um utilizador e consulta os registos relevantes.
3. Recuperar: a equipa restaura uma cópia recente num ambiente seguro e confirma o período de dados que poderia perder.
4. Publicar: utilizadores autorizados preparam uma versão de teste e identificam todas as aprovações necessárias.
5. Revogar: o proprietário remove ou reduz uma permissão e confirma que a alteração fica registada.

A checklist Catalyst dá prioridade ao código, à documentação e aos recursos editáveis que permitem a outra organização continuar o projeto. Essa é a medida correta: continuidade comprovada, e não simples posse de ficheiros.

Sinais de alerta antes de aceitar o projeto

Pare e esclareça a situação se a aplicação só compila no portátil de um programador, se as contas das lojas pertencem a alguém que já não participa no projeto, se existem segredos dentro do código, se nunca foi testada uma cópia de segurança ou se o design não corresponde ao produto publicado.

Desconfie também de documentação extensa mas vaga. “Está na nuvem” ou “tem análise instalada” não identifica serviço, conta, projeto, administrador, faturação nem recuperação. Uma linha concreta com estes dados vale mais do que várias páginas genéricas.

Questões contratuais e direitos de propriedade variam consoante o país e o acordo. Quando o risco o justificar, confirme-os com aconselhamento jurídico qualificado. A revisão técnica revela elementos em falta, mas não substitui o contrato.

Como a Appfyl prepara a continuidade

Num novo projeto, começamos por mapear a propriedade do código, design, lojas, infraestrutura, dados, serviços externos e apoio. Assim, o cliente consegue criar antecipadamente as contas que devem ficar em nome da empresa.

Antes do lançamento, relacionamos a versão aceite com os respetivos repositórios, fontes de design, ambientes e problemas conhecidos. Quando recebemos um produto existente, primeiro verificamos o que realmente pode ser compilado, acedido e recuperado. Essa prova é mais útil do que assumir que uma pasta antiga está completa.

Ao comparar propostas, consulte as perguntas a fazer a uma empresa de desenvolvimento e inclua a entrega na conversa. O brief de estimativa da Appfyl ajuda ainda a listar os perfis, serviços e integrações que precisarão de responsáveis.

Veja como a Appfyl transforma escopo em produtos lançados. Ver cases da Appfyl.

Perguntas frequentes