Que tipo de relatório ou documentação esperar dos meus programadores

5

Primeiro, eu não sou programador nem tenho experiência em programação. Eu sou um empreendedor que tinha uma ideia de site e contratou programadores para construí-lo. Isso vem acontecendo há um ano. Ele usa o Wordpress com alguns plugins como Buddypress, Bbpress, etc, mas também muitos códigos customizados.

Eu dou tarefas aos programadores e eles fazem isso e as tarefas funcionam como eu quero, mas eles não apresentam nenhum relatório ou documentação sobre o que eles fizeram e como tudo foi codificado, etc.

Mas meu problema é - e se de repente eles desaparecerem e eu tiver que fazer com que outros programadores continuem trabalhando no site? Os novos programadores podem fazer um bom trabalho quando não há nenhum relatório ou documentação, etc?

É claro que há um relatório meu para os programadores, dizendo-lhes o que fazer e quais funções eu espero que as tarefas executem. Mas quando feito, eles não me apresentam nenhum relatório ou documentação. Eles apenas dizem que a tarefa está feita e eu verifico e está feito.

Se tal relatório ou documentação for necessário, que tipo devo solicitar a esses programadores atuais?

Ou estou sendo desnecessariamente paranóico?

    
por Mr Ley 14.05.2015 / 09:16
fonte

4 respostas

4

Eu acredito que o problema não é sobre qual documentação você deve pedir. É sobre como você pode verificar se ele é válido e realmente ajudará o novo desenvolvedor a escolher o local anterior à esquerda. É fácil verificar se o recurso real funciona, mas não é fácil verificar a documentação, independentemente do tipo de documentação que você solicitar.

Isto é como eu faria: primeiro, eu adicionaria a exigência de exatamente o que você quer. Eu diria que "Cada recurso deve ser documentado o suficiente para que o novo desenvolvedor tenha uma compreensão geral dele, por que ele existe e por que foi implementado da maneira como foi." Eu deixaria para os desenvolvedores decidir como documentar melhor o trabalho deles. Eles podem criar uma documentação externa abrangente ou podem tornar o próprio código autodocumentado com documentação externa mínima. Depois disso, contrataria um desenvolvedor externo diferente para fazer uma revisão de código de seu trabalho. Este desenvolvedor iria "emular" um novo desenvolvedor e tentaria entender o que o aplicativo deve fazer e se está fazendo corretamente. Então ele produz um relatório baseado em como foi fácil para ele. Isso pode ser feito periodicamente a cada poucas semanas / meses.

    
por 14.05.2015 / 10:01
fonte
3

Eu acho que as chances são que você NÃO quer qualquer documentação de código dos programadores.

A razão pela qual você afirma que acha que pode querer uma documentação é:

"Os novos programadores podem fazer um bom trabalho quando não há nenhum relatório ou documentação, etc."

Portanto, a documentação não é para você ler, não é um manual para o produto, ela não lhe dá nenhum benefício em si.

Se você não conseguir novos programadores durante a vida útil do seu produto. Você terá pago seus programadores para escrever documentos que nunca são usados.

Na minha opinião, seus novos programadores hipotéticos provavelmente não os lerão. Os programadores tendem a não ler a documentação do código por várias razões e isso é geralmente reconhecido com metodologias modernas de programação 'ágil'.

Então eu digo: não peça aos programadores para documentar seu código.

No entanto! O que você DO precisa documentar são seus requisitos e quais testes foram executados para garantir que eles sejam atendidos.

por exemplo.

Requirement 1: "when there is an error, make the button red"

você precisa disso porque os novos programadores hipotéticos não saberão o que o código deve fazer.

Seus programadores atuais entendem o projeto, então quando você diz a eles

Requirement 2: 'Make the button blue'

Lembram-se do seu requisito anterior e tornarão o botão azul quando não estiver com erro e vermelho quando estiver.

No entanto, os novos programadores não estavam por perto quando você solicitou o requisito 1. assim eles ficarão azuis o tempo todo.

Você terá que lembrar de todos os requisitos e informá-los:

Requirement 2 : 'make the button blue, unless it is errored in which case it should be red'

É impossível lembrar de todos os requisitos para projetos pequenos, e o que é pior, a combinação de requisitos, ou seja, que o estado vermelho substitui o estado azul, nunca é realmente indicado. É aí que entra o seu teste, você terá testado o aplicativo funcionado após o requisito 2 e escrito

"Tested normal page ok, tested error page ok"

Isto irá dizer aos novos desenvolvedores que a página de erro é Suposta para ter um botão vermelho, e não é um bug que precisa ser corrigido.

O que você precisa para se proteger da perda é a grande figura do que seu aplicativo deve fazer. Essa é a única coisa que existe apenas nas cabeças dos desenvolvedores no momento e é realmente algo que só você pode documentar.

    
por 14.05.2015 / 13:46
fonte
1

Você deseja um documento de design de alto nível que descreva os grandes blocos e sua interação e, em seguida, o design funcional que descreve como esses blocos foram implementados. Leia sobre UML para os principais conceitos de design (mas não os faça entregar documentos UML, por favor - eles entram em muitos detalhes, você só quer as visões gerais)

Muitas vezes, a documentação pode ser suficiente com um documento de texto simples descrevendo a arquitetura geral, ferramentas usadas (e versões!) - apenas o suficiente para permitir que um novo desenvolvedor entenda os conceitos e suposições usadas para que eles entrem no código. descubra os detalhes exatos da implementação.

Você pode exigir documentação completa, eu trabalhei em lugares (polícia, governo) que realmente precisam saber exatamente como algo funciona, e tal documento é uma coisa bonita de se ter - mas rapidamente fica mais caro produzir, e acho que seria um exagero para as suas necessidades, por isso tome cuidado para não ir longe demais na documentação. Há um ponto ótimo entre ninguém, o suficiente para entender o produto e demais.

    
por 14.05.2015 / 09:44
fonte
-1

Olá, se eu entendi muito bem, você quer ter certeza de que, quando seus programadores atuais não estiverem mais lá para gerenciar seu site, você poderá contratar alguém e será fácil para eles escrever e não reinventar a roda. bom.

bons programas são para eles mesmos uma boa documentação, desculpe, pode não haver uma documentação em papel mas está na codificação, você pode não saber, mas os programadores irão. apenas sempre lembre-os de manter a documentação apropriada. quando o novo programador chegar, ele sabe que deve encontrar as documentações.

    
por 14.05.2015 / 17:27
fonte