Escrevendo o manual de um desenvolvedor para toda a empresa

17

Eu trabalho para uma pequena empresa. O braço de desenvolvimento de software da empresa antes de eu ser contratado consistia em um sujeito sobrecarregado e autodidata. Agora que estou escrevendo software para a empresa há alguns anos, fui incumbido de estabelecer práticas formais de desenvolvimento de software em toda a empresa. Atualmente, não temos diretrizes além de

Escreva o código, teste-o, coloque-o em um arquivo .zip e envie-o ao cliente. Pontos de bônus para TDD e controle de versão.

Meu chefe quer que eu escreva um manual do desenvolvedor de software que defina os processos, protocolos, ferramentas e diretrizes gerais que usamos para fazer as coisas. Em outras palavras, ele quer um livro "Isto é o que fazemos aqui" para facilitar a familiarização de um novo funcionário com a maneira como fazemos as coisas, além de ajudar meu chefe a entender o que seus subordinados estão fazendo e como eles fazem. isto.

Na minha opinião, estou estabelecendo uma base e ela precisa ser feita corretamente. Como você escolheria tópicos para esse manual? Você pode fornecer alguns tópicos de exemplo?

Nota: Se isso for importante, somos principalmente uma loja Microsoft .NET. E estamos analisando práticas ágeis como XP e Scrum, mas podemos ter que modificá-las bastante para fazê-las funcionar em nossa empresa.

Phil
fonte
3
Seu processo atual é muito ruim. Você tem suporte da empresa para alterar seu processo atual, não será barato, o tipo de alteração necessária exigirá dinheiro. Existem muitos livros sobre o assunto, a maioria dessas práticas possui ferramentas, necessárias para implementar nelas de uma maneira que não exija muito esforço.
Ramhound
comprando tópicos do manual?
Gnat
1
@gnat Bom ponto. Veja editar.
Phil
boa edição (você aparentemente seguiu o link). Eu também mudaria Quais tipos de tópicos você acha que são importantes ... para algo como Como você avaliaria a importância dos tópicos ... - assim, seria mais alinhado com as orientações de Jeff, tanto quanto eu as entendo.
Gnat #
1
Não estou realmente preocupado em como avaliar a importância dos tópicos, pois acho que já posso fazer isso. Pelo contrário, estou procurando exemplos. Sempre considerei as respostas às perguntas abstratas melhores quando acompanhadas de exemplos. Veja editar. BTW, agradeço a sua ajuda para melhorar minha pergunta.
Phil

Respostas:

20

Eu dividiria em seções como

  • Equipe atual - nomes e títulos (idealmente com fotos)
  • Aplicativos, logins para eles, dados para saber e solicitações de permissão para enviar
  • Marcadores para sites da empresa e sites externos importantes para os negócios
  • Aplicativos que a empresa usa para comunicação, e-mail, reserva de sala de conferência, sharescreen
  • Procedimentos para atividades relacionadas à empresa, como despesas de recebimento, reservas de viagens
  • Configuração da máquina do desenvolvedor. Descreva o processo de configuração de uma nova máquina de desenvolvedores em detalhes. Geralmente, é "esperado" que leve apenas um dia, mas geralmente leva de três a cinco dias na realidade.
  • O processo de desenvolvimento, como o trabalho é rastreado, atribuído e atualizado e quais ferramentas são usadas.
  • Como testar, o que testar, quando testar, onde testar.
  • Padrões de codificação, incluindo convenções de nomenclatura de arquivos e padrões específicos de idioma.
  • Como lidar com bugs, onde documentá-los, como proceder para corrigi-los.
  • processo de implantação, quais são as principais coisas a saber para os impulsos de produção.
  • Como documentar, o que documentar, quando documentar.
  • Onde as coisas 'estão', por exemplo, local (is) para Código, Dados, Padrões, Documentação, Links e outros ativos.

A modularidade também permitirá que você ou outras pessoas atualizem as peças separadamente, por exemplo, os nomes e as posições dos funcionários mudam com frequência à medida que as pessoas vão e vêm.

Para cada seção, eu tentaria escrevê-lo do ponto de vista de 'novato'. O mais importante será garantir que realmente faça sentido para um novato. Seu chefe obviamente não é a pessoa certa para revisar isso, pois ele não é o público-alvo. Ele está certo em querer, apenas verifique se o conteúdo não acaba sendo testado por ele. Além disso, um 'novato' tem apenas 1 semana como sendo um novato ... e apenas um ponto de vista. Portanto, é provável (e recomendado) que o documento seja refinado a cada novo funcionário. Na verdade, é uma tarefa muito boa atribuí-los também para a primeira semana, ou seja, "Atualizar o manual para iniciantes".

Para Agile / SCRUM:

A parte mais difícil de fazer Agile e SCRUM é 'realmente' fazê-lo.

Para ler, começaria em http://agilemanifesto.org/ e partir daí.

Eu também leria o conhecido http://www.halfarsedagilemanifesto.org/, que acrescenta peso ao fato de que você realmente precisa adotar todos os aspectos para que ele funcione. Se você precisar modificar fortemente o Agile para suas organizações, é provável que as pessoas desejem os benefícios - sem usar os processos corretos. Esse fato em si deve ser apresentado para afastar qualquer meia-afirmação.

Michael Durrant
fonte
6
Eu gosto da frequência com que você está editando isso. Quão ... ágil da sua parte. :)
Phil
Não estamos necessariamente querendo modificar os princípios ágeis em geral. Modificamos apenas práticas específicas, como o XP, pois não temos realmente mão de obra para implementar todas as funções necessárias. Essa pode ser outra pergunta para outro dia.
Phil
Desculpe, removi a resposta no momento porque a pergunta foi modificada.
Phil
1
Os pontos de bónus se você configurar um wiki empresa para manter esta informação ...
Spencer Rathbun
Oi Spencer, isso é interessante. Também comecei a usar um wiki do github com descontos. Quaisquer pensamentos sobre como eles se comparam. Obviamente, muitas pessoas conhecem o github a partir do código e a marcação do SO, por isso é fácil ser adotado.
Michael Durrant
4

Parece que você precisará introduzir algumas práticas antes de documentá-las!

a) Controle de origem - como você armazena suas fontes e faz o controle de revisão

b) Gerenciamento e rastreamento de release - como você faz uma construção, numera um release, compara um candidato a release atual a um release anterior

c) Gerenciamento de problemas - como você rastreia bugs em seus releases.

Essas são coisas bastante básicas, mas podem levar muito tempo (e possivelmente custam dinheiro) para serem implementadas.

Scott C Wilson
fonte
2
+1 por simplificar e se concentrar em questões importantes. Realmente não precisamos de mandatos de "grande governo" sobre estilos de codificação.
Kirk.burleson
3

Tópicos que eu incluiria no manual do desenvolvedor:

  • Funções / cargos dentro do departamento e suas responsabilidades correspondentes
  • Requisitos de software da máquina do desenvolvedor (ou seja, ambiente de desenvolvimento necessário)
  • Onde e como acessar o repositório de código-fonte
  • Ferramentas de desenvolvimento sendo usadas (por exemplo, IDE)
  • Estilo / padrões de codificação
  • Padrões de documentação
  • Processo de teste
  • Processo de compilação
  • Processo de implantação
  • Processo de suporte e gerenciamento de problemas
  • Onde obter a versão mais atualizada deste manual

Lembre-se de que este manual deve conter apenas itens específicos ao desenvolvimento, e não informações de toda a empresa (que devem constar no manual do funcionário).

Bernard
fonte
2

Uso do controle de origem

  • Qual ferramenta de controle de origem você está usando.
  • Sintaxe de comandos / ferramentas comuns no IDE.
  • Estratégia de ramificação / mesclagem.
  • Qual deve ser a unidade de uma confirmação? Quanto tempo demora para que um arquivo seja retirado / não confirmado?
  • Qual nível de "doneness" indica um commit / check-in? Compila? Os testes de unidade são aprovados? Revisado?
  • O que é esperado para ser incluído nas notas para uma confirmação / check-in.
  • Procedimentos de reversão.
JohnMcG
fonte