Eu estava trabalhando em um projeto há três meses e, de repente, outro projeto urgente apareceu e me pediram para mudar minha atenção.
A partir de amanhã, voltarei ao projeto antigo. Percebo que não me lembro exatamente do que estava fazendo. Não sei por onde começar.
Como posso documentar um projeto para que, a qualquer momento, não demore mais do que alguns minutos para sair de onde eu saí. Existem práticas recomendadas?
project-management
documentation
Aquarius_Girl
fonte
fonte
Respostas:
Eu só queria contribuir com alguns conselhos que não serão úteis na sua situação atual, mas você pode começar a implementá-lo agora para ajudar no futuro.
É claro que existem candidatos óbvios, como listas de tarefas e registros de problemas; analisar os problemas adicionados recentemente deve fornecer uma pista sobre o que você estava fazendo quando foi retirado do projeto.
Nos projetos anteriores em que trabalhei, esperava-se que as pessoas mantivessem um registro do projeto como parte do processo de gerenciamento da qualidade. O conteúdo não era muito claramente especificado, mas a idéia era manter um registro diário das coisas relacionadas ao projeto que podem ser úteis para o trabalho contínuo no futuro ou para as atividades de revisão após a conclusão; por exemplo:
Observações sobre a qualidade do projeto
Itens / problemas de tarefas que você não gostaria de registrar formalmente em um rastreador de problemas
Decisões de design - especialmente as não triviais.
Problemas encontrados e como você os solucionou. Muito importante, na minha opinião pessoal: sempre que encontrar um problema, observe-o no log.
Os dois últimos pontos são muito importantes. Muitas vezes encontrei uma situação ou problema semelhante - às vezes em um projeto completamente diferente - e pensei "hmm, lembro-me de passar um dia nisso, mas qual era a solução novamente?"
Quando você voltar a um projeto depois de um tempo, a leitura do log do projeto (seja seu ou do desenvolvedor mais recente) deve colocá-lo de volta ao fluxo que você tinha quando saiu e avisá-lo sobre algumas das armadilhas que você caso contrário, poderá cair novamente.
fonte
As listas de tarefas são mágicas. Geralmente, você precisa manter uma lista de tarefas ativas para cada projeto e, mesmo que esteja ocupado com a programação, se você pensa em algo que precisa ser feito e não pode fazê-lo imediatamente, ele entra na lista. Mantenha essa lista em um local conhecido, em uma planilha ou arquivo de texto na pasta do projeto eletronicamente ou no seu diário de papel.
Além disso, sempre que você deixar o projeto durante a noite (ou no final de semana), faça um post-it e escreva a próxima coisa que você faria na nota e cole-a no monitor. Isso aumenta a probabilidade de você voltar rapidamente na manhã seguinte.
Editar :
Devo mencionar que as listas de afazeres (listas de afazeres priorizadas especificamente segregadas por local e projeto) são uma parte essencial do livro Getting Things Done , que eu achei altamente influente.
fonte
todo
alvo em seu makefile que os despeja também é útil.O que fazer agora?
Meu palpite é que você não fez nada na próxima seção. Portanto, procurar uma lista de tarefas não funcionará.
Como tornar isso melhor para si mesmo no futuro?
Primeiro, você precisa ter um sistema para acompanhar seus todos. Você tem esse sistema agora? Como você gerencia seu projeto atual?
Eu poderia ser atropelado por um ônibus amanhã e minha equipe teria uma boa idéia de mais de 90% dos meus itens de ação. Isso ocorre porque eu tenho um sistema coeso para documentar meus:
Além disso, eu uso um VCS e comento meu código, quando apropriado.
Isso funciona para mim e minha equipe desde que eu sou o desenvolvedor principal. Você pode usar algum tipo de sistema de rastreamento de problemas para uma equipe. Ou um backlog ao trabalhar com o Agile. Há uma tonelada de opções. Se você está realmente interessado nisso, leia Getting Getting Done ou outras metodologias relevantes de gerenciamento de tarefas, que existem quase exatamente por causa do que você descreve.
Qual é o objetivo?
As especificidades do sistema são menos relevantes do que o sistema coeso e você o utiliza . E que você use. E use-o. Isso é importante. Mais importante do que um bom sistema perfeito que você não usa. Não faça "bem, a maior parte do meu trabalho está aqui, mas alguns estão na minha cabeça" ou você vai se odiar voltando a um projeto.
Além disso, verifique se seus comentários explicam "por que" em vez de apenas o "quê" para o código. É muito mais fácil ler "isto é para corrigir um bug no IE8" e lembrar o que o código faz do que um comentário simplesmente explicando os detalhes técnicos.
fonte
Na minha opinião, existem duas partes para "retomar" um projeto de código:
Essa é uma daquelas coisas que, se você estiver controlando a versão da maneira certa, será o seu "outro cérebro".
De onde você parou ? Contanto que você esteja enviando código com freqüência, observe seu último conjunto de alterações. Provavelmente, você jogará algo em sua mente. Caso contrário, observe os poucos anteriores, começando pelos commits mais antigos e repetidos.
Quanto ao que resta a fazer , um backlog deve servir a esse propósito (ou uma lista de tarefas ou o que você quiser nomear. Basicamente, itens para o futuro).
Não sou desenvolvedor de software em período integral. Sou um programador que corta as noites e fins de semana. Por esse motivo, quando o trabalho ou outras coisas que não são de programação têm prioridade mais alta, às vezes eu posso passar dias e semanas sem sequer exibir meu código com um olhar. O acima exposto provou ser bastante eficaz.
fonte
Esta não é uma resposta completa - já existem várias muito boas mencionando coisas importantes, como usar o VCS e o software de gerenciamento de projetos -, mas um adendo que acrescenta alguns pontos que eu não vi em nenhum outro, que eu acho que é muito útil, e espero que outras pessoas também achem útil.
1. Nenhuma tarefa é muito cedo ou muito pequena para ser anotada
As pessoas costumam fazer listas de tarefas para as coisas que planejam fazer no futuro , mas como a programação exige concentração e como podemos ser interrompidos a qualquer momento , achei útil anotar até o que estou fazendo agora, ou o que estou prestes a começar em questão de segundos . Você pode sentir que está na zona e não pode esquecer a solução que acabou de acertar naquele momento aha , mas quando seu colega de trabalho cai no seu cubo para mostrar uma foto do dedo infectado dele , e você está capaz de finalmente se livrar dele, começando a roer seu próprio braço , você pode desejar ter anotado uma nota rápida, mesmo que apenas em uma nota Post-It ™.
É claro que algum outro meio mais persistente pode ser melhor (gosto particularmente do OmniFocus ), mas a questão é pelo menos tê-lo em algum lugar , mesmo que você termine em 20 minutos e jogue o Post-It ™ fora. Embora você possa descobrir que essas informações se tornam úteis, colocar folhas de ponto ou faturas para o cliente ou quando seu chefe / cliente perguntar o que você está trabalhando e não se lembra. Se você soltar todas essas anotações em uma caixa, gaveta ou pasta, quando ocorrer uma grande interrupção - um projeto de interrupção -, será possível examiná-las e lembrar-se de muitas coisas que você fez para levar seu código ao ponto em que você encontre-o quando retornar ao projeto.
2. Use um quadro branco em sua mesa para capturar idéias gerais
Eu tenho um quadro branco de 3 "x 4" ao lado da minha mesa; portanto, quando inicio um projeto, posso pensar em soluções para todos os problemas que percebo em um projeto. Pode ser diagramas arquitetônicos, casos de uso, listas de riscos e obstáculos ou qualquer coisa que lhe pareça relevante.
Algumas abordagens mais formalizadas exigem que você gere diagramas e casos de uso e assim por diante como "entregáveis" em algum formato eletrônico ou em papel, mas acho que isso pode criar muito trabalho extra e se tornar uma série de subprojetos que terminam se divorciar do objetivo real do projeto principal e apenas parte de um processo formalizado que você precisa fazer, mas que ninguém presta muita atenção. Um quadro branco é a coisa mais simples que realmente funciona, pelo menos na minha experiência. É tão persistente quanto você deseja (com uma câmera) e, o mais importante, permite que você descubra suas idéias imediatamente.
Eu acho melhor com uma caneta na mão, então jogar meus pensamentos em uma superfície branca vem naturalmente para mim, mas se você não acha que esse é o seu caso, aqui estão algumas perguntas que podem ajudá-lo a decidir o que é relevante :
(Quando escrevo as idéias pela primeira vez, só me preocupo com elas fazendo sentido para o meu eu atual. Depois que elas caem, posso olhar mais criticamente para elas e fazer alterações para garantir que elas façam sentido para o meu eu futuro ou para os outros. Preocupar-se demais sobre a comunicação com os outros à medida que você os escreve inicialmente pode levar ao bloqueio dos escritores - uma mente entupida por objetivos concorrentes.
Eu recomendo que você gaste o dinheiro para comprar um quadro branco decente, pelo menos 3 "x 4", e pendure-o no espaço em que você normalmente trabalha. Há muitas vantagens de um quadro branco físico sobre qualquer sistema virtual.
Você perde muitos dos benefícios se usar um quadro branco em uma sala de reunião e tirar uma foto com seu telefone. Se você ganha dinheiro com a programação, vale a pena o custo de um quadro branco decente.
Se um outro projeto interromper o que encheu o quadro branco, talvez seja necessário recorrer ao instantâneo do telefone, mas pelo menos você terá isso em três meses quando o projeto "urgente" for concluído e você precisará volte para o outro. Se você quiser recriá-lo em seu quadro branco, provavelmente levará apenas 15 minutos e poderá descobrir que pode melhorar bastante no processo, o que faz com que esse pequeno investimento de tempo valha a pena.
3. Informar as partes interessadas sobre o custo de interromper um projeto
Acho útil a metáfora de um avião: iniciar e concluir um projeto é como pilotar um avião. Se você sair no meio do voo, o avião não ficará parado no ar, esperando que você volte a ele, e você precisará de alguma maneira de viajar do projeto / vôo atual para o próximo. De fato, se você estiver no meio de um voo de Phoenix para Fargo e lhe disseram que precisa interromper o voo para pegar outro avião de Denver para Detroit, precisará pousar o primeiro avião em Denver (que felizmente, não está longe da sua trajetória de voo - nem sempre é o caso de interrupções reais) e alguém precisa descobrir o que fazer com a carga e os passageiros. Eles não vão apenas sentar e esperar para sempre.
O ponto disso para os projetos é que a transição de um projeto para outro implica uma grande despesa de tempo e deixa muitas perdas a serem resolvidas.
Em um projeto, há obviamente e inevitavelmente muita coisa em sua cabeça enquanto você trabalha, e nem todo pensamento pode ser serializado em um meio escrito, e nem todo tipo de pensamento que é serializado permanecerá quando desserializado. Embora possamos capturar parcialmente nossos pensamentos por escrito, é um formato com perdas.
O problema (a meu ver) é que os gerentes de projetos e outras pessoas de negócios pensam nos projetos como uma série de etapas que podem ser reordenadas com freqüência (a menos que exista uma dependência explícita no gráfico de Gantt) e podem ser facilmente distribuídas entre as pessoas ou atrasado até que seja mais conveniente para os negócios.
Qualquer pessoa que tenha feito alguma programação sabe que os projetos de software não podem ser tratados como blocos de Lego para serem movidos da maneira que você quiser. Acho que a metáfora das viagens aéreas, pelo menos, dá às partes interessadas algo concreto que elas podem pensar que claramente não pode ser tratado como uma série de etapas díspares a serem reordenadas por um capricho. Pelo menos, é fácil entender o seu argumento de que há um custo para essas interrupções. É claro que ainda é uma decisão deles, mas você deseja conscientizá-los antes que eles interrompam um projeto para dar outro. Não seja combativo, mas ofereça informações úteis e a perspectiva útil do desenvolvedor, pronto para fazer o que for necessário, mas apenas ofereça informações das quais eles talvez não saibam se você não lhes contar.
Em resumo:
fonte
Você pode consultar o histórico do projeto em seu software de controle de versão de três meses atrás. Leia suas mensagens de confirmação e as diferenças mais recentes para ter uma idéia do que estava trabalhando.
fonte
O uso de um sistema de controle de origem com estratégias apropriadas de ramificação e fusão, em conjunto com sistemas de rastreamento de problemas (como Redmine ou GitHub ), ajuda a compartimentar as alterações que você fez, orientar e documentar seu 'contexto' ausente como uma parte natural do fluxo de trabalho.
fonte
Há muitas respostas longas. Este é breve sobre o que mais me ajuda:
No entanto, Diffs, Commit comments, Post-It notes, Todo-Lists ou Kanban-Board podem ser mal interpretados ao longo do tempo por falta de contexto. Então, aqui está a coisa mais importante:
CÓDIGO LIMPO.
fonte
main
, que para um programa de tamanho significativo será bastante abstrata. Eu posso mergulhar mais fundo e ver a arquitetura de como o programa se limpa, por exemplo. Além disso, código limpo significa que funções / variáveis / etc. tenha nomes que façam sentido e faça uma declaração sobre seu significado. Se eu escrever o código Espaguete / Somente Gravação, em geral, acordarei na manhã seguinte / mês / ano, observarei o meu código e o único pensamento será wtf-did-i-do-there. É o mesmo quando ..Primeiro, isso implica que há alguma descrição de alto nível e estrutura de código no projeto que você pode entender facilmente em alguns minutos - em oposição a um zilhão de linhas de código sem estrutura aparente e sem comentários.
A seguir, são apresentadas as melhores práticas que adotei ao longo de uma carreira de mais de 20 anos em projetos muito pequenos a muito grandes e elas serviram a mim e a minha equipe. Aplique na ordem listada à medida que seu projeto cresce:
Use o controle de versão para obter um histórico gratuito do que aconteceu, quando e quem aplicou as alterações. Também oferece fácil retorno a uma versão anterior a qualquer momento.
Modularize seu código (dependendo da linguagem e do ambiente de programação, use classes, módulos, pacotes, componentes).
Documente seu código. Isso inclui a documentação resumida na parte superior de cada arquivo (o que isso faz? Por que? Como usá-lo?) E comentários específicos no nível de funções, procedimentos, classes e métodos (o que isso faz? Argumentos e valores de retorno / tipos? efeitos colaterais?).
Adicione
TODO
eFIXME
comente enquanto estiver codificando. Isso ajuda a lembrar os porquês e as peculiaridades que inevitavelmente entrarão em sua base de código e que mais tarde você terá que perguntar ao WTF ?! . Por exemplo:Crie o hábito de desenhar diagramas para documentar a estrutura e o comportamento complexo, como sequências de chamadas entre módulos / objetos / sistemas, etc. Pessoalmente, prefiro o UMLet , pois é rápido de usar, cria bons gráficos e, o mais importante, não interfere no seu caminho. . Mas é claro que você deve usar qualquer ferramenta de desenho que considere adequada. Lembre-se de que o objetivo de tais desenhos é se comunicar de forma sucinta, não especificar um sistema em detalhes minuciosos (!!).
Adicione testes de unidade logo no início. Os testes de unidade não são ótimos apenas para testes de regressão, mas também são uma forma de documentação de uso para seus módulos.
Adicione documentação externa ao código logo no início. Comece com um README que descreva as dependências necessárias para executar e desenvolver o projeto, como instalá-lo, como executá-lo.
Crie o hábito de automatizar tarefas repetitivas . Por exemplo, os ciclos de compilação / compilação / teste devem ter scripts de alguma forma (por exemplo, no uso de JavaScript
grunt
, em Pythonfabric
, em JavaMaven
). Isso ajudará você a acelerar rapidamente quando voltar.À medida que seu projeto cresce, inclua mais documentação gerando documentos de código-fonte (usando alguma forma de comentários no estilo JavaDoc e uma ferramenta apropriada para gerar HTML ou PDF a partir dele).
Se o seu projeto crescer além de um único componente e tiver uma implantação mais complexa, adicione documentação de design e arquitetura . Observe novamente que o objetivo disso é comunicar estrutura e dependências, em vez de detalhes minuciosos.
fonte
Além das sugestões sobre o rastreamento do projeto, as listas de tarefas, o Trello, etc., algo que li uma vez que ajuda se você pratica o TDD é sempre se afastar do projeto com um novo teste de falha a ser implementado sempre que você voltar ao projeto (amanhã , na próxima semana ou no próximo mês)
Sente-se, faça 'Executar testes' e continue de onde parou.
fonte
next-steps
. Não sei ao certo o que suas preocupações sobre as especificidades da abordagem de controle de revisão têm a ver com a premissa básica de um teste reprovado como uma ajuda para dar um pontapé inicial no cérebro ao voltar a algo. Novamente, isso foi proposto, além das abordagens padrão, tais como atrasos, listas de tarefas, etc.Além dos comentários / listas de tarefas / confirmações, é importante ser realista.
Dependendo do tamanho, da complexidade e do estado em que você deixou o seu trabalho, o início de um projeto pode demorar um pouco. Para uma base de código substancial de muitos componentes em interação, pode levar dias para atingir a velocidade máxima.
Boa e velha paciência será útil.
Quando sobrecarregado depois de voltar a um projeto depois de um tempo, geralmente pego a unidade de tarefa mais simples e menor e a implemento. Isso me impede de me perder tentando lembrar de muitas coisas ao mesmo tempo e aumenta a confiança um pouco. Na maioria das vezes, eu me pego automaticamente pegando tarefas cada vez maiores em poucas horas.
fonte
Eu mantenho um diário diário do trabalho que faço. O que eu fiz hoje, o que foi difícil hoje, qual é o próximo passo, que idéias eu tive hoje para o futuro. Também adiciono um pouco de narrativa sobre como foi o dia: houve uma conversa ou reunião interessante? Algo ficou com raiva ou deleite? Isso ajuda a colocar as coisas em perspectiva quando mais tarde leio meu diário.
Quando volto a um projeto depois de um tempo, li as últimas entradas do diário para me familiarizar com o projeto. Todos esses pequenos detalhes do dia a dia são incrivelmente importantes para lembrar o processo de desenvolvimento. Eles realmente fazem muita diferença em comparação com uma lista de tarefas ou documentação regular do projeto, pois lembram como foi trabalhar no projeto e não apenas como usar o produto.
fonte
Para mim, acho que o método mais simples de retomar projetos é apenas manter um registro constante de anotações em seu trabalho. Acho que o 'OneNote' da Microsoft é particularmente bom para manter e agrupar páginas de anotações. Em particular, a barra de pesquisa torna extremamente fácil encontrar rapidamente suas anotações sobre algo.
Aqui estão algumas coisas que faço no OneNote que me ajudam a retomar o progresso nos projetos:
Registros diários / semanais - Mantenha um registro diário ou semanal do progresso para ajudá-lo a descobrir o progresso que você já fez em um projeto.
Lista de tarefas - eu tenho uma lista geral de tarefas, mas também mantenho uma lista de tarefas separada para os projetos nos quais estou trabalhando, para lembrar as coisas que ainda tenho que fazer por um projeto. Às vezes, também deixo // TODO: itens no meu código.
Notas do projeto - As coisas que observo incluem links para itens de rastreamento de problema / projeto, trechos de código, problemas encontrados, decisões tomadas, planos e descrições de possíveis soluções, lista de alterações de código, links para o diretório do repositório de códigos, e-mails para o projeto e links para Documentação do projeto.
Assim, sempre que volto a um projeto, posso abrir minhas anotações e quase instantaneamente posso ver quanto progresso foi feito no projeto, quanto trabalho resta para fazer e até ver minha linha de pensamento.
fonte
Para projetos simples, faço o seguinte:
fonte