Manuais - Como atualizado?

10

Se você possui um produto que está no mercado há muito tempo, mas ainda está em desenvolvimento ativo diariamente - com que frequência os manuais devem ser atualizados? Se seus usuários são atualizados constantemente para a versão mais avançada devido ao fato de sua organização considerar adequado, as correções de bugs mais recentes estão sempre na versão fornecida. Ou seja, você pode corrigir um bug um dia e no dia seguinte ele está atingindo a produção.

Brian
fonte
11
Estamos falando de manuais impressos ou on-line? Existem pelo menos algumas formas diferentes que isso pode assumir.
JB King
Manuais online (PDF)
Brian

Respostas:

4

Eu atualizaria o manual:

  1. Para cada versão principal e
  2. Quando novos recursos importantes se tornam estáveis ​​e maduros o suficiente para que você saiba que eles não serão alterados a cada cinco minutos.
Robert Harvey
fonte
3

atualize o manual (PDF) sempre que uma alteração de código alterasse as instruções do manual - basta fazer a atualização do manual como parte do processo de liberação

se os usuários confiarem no manual para lhes dizer como usar o produto e o produto mudar, é apenas senso comum que as seções relevantes do manual também devem mudar

Steven A. Lowe
fonte
11
então, se nenhum escritor técnico da equipe, atualize você mesmo?
22710 Brian
@ 0A0D - se você não tem um escritor, não tem muita escolha, a menos que haja uma equipe de teste ou suporte que possa fazê-lo.
JeffO
11
Eu tenho o documento 'arquivos de origem' como parte dos meus projetos. Eles são sempre atualizados ao mesmo tempo que o código. Eles são versionados com releases e gerenciados usando as mesmas ferramentas de gerenciamento de fontes que os demais arquivos do projeto (vá para Mercurial!). Eu tenho um conjunto bastante padrão de manuais para acompanhar um projeto e todos eles são gerenciados da mesma maneira (guia do usuário, guia de configuração / instalação, notas de versão e nossos próprios documentos técnicos de ref / spec).
2

Em 2010, ainda estamos nos referindo à documentação impressa? Por quê? ;)

Com toda a seriedade, a documentação (ajuda do aplicativo "F1", PDF ou documentação online) deve fazer parte de cada versão. Zero desculpas. É simples assim "publicar". De fato, na IMO, não há desculpa para não atualizar a documentação regularmente (online e PDF), mesmo entre os lançamentos, assim que os problemas forem conhecidos e corrigidos. Ele não precisa do mesmo nível de controle de qualidade - nem de perto.

Mark Freedman
fonte
2

Suponho que você esteja falando sobre a documentação do usuário final. Escrever documentação é uma dor no @ $$ e, embora eu tenha desenvolvido alguma técnica para me convencer do inverso, ainda tenho problemas com isso. É assim que eu tento gerenciá-lo:

Integre a atualização da documentação ao seu DoD ( Definição de concluído )

Isso garantirá que sua documentação esteja atualizada no final de cada conclusão da história do usuário.

Aqui está a definição de done que escrevemos. Tentei manter as formatações originais, para que você entenda. É uma página A4 colocada no quadro branco.

---------- 8 <------------ Corte Aqui ------------ 8 <----------

O não negociável

Definição de "Concluído"

  • Código com 80% de cobertura de teste de unidade, confirmado no repositório

  • Capturas de tela, se aplicável (1024x728, 395x281, 170x121 e 729x329)

  • Descrições de recursos, se aplicável (50 caracteres, 100 caracteres)

  • Documentação completa do usuário final

  • O que há de novo arquivo atualizado corretamente

---------- 8 <------------ Corte Aqui ------------ 8 <----------

Claro que você pode adicionar um processo de revisão na documentação. Temos isso, já que nenhum de nós fala inglês nativo.

Uma das vantagens da Definição de Concluído dessa maneira é que seu produto pode ser entregue no final de cada conclusão da história do usuário.

Use esta técnica em combinação com esta .


fonte
1

Na minha organização, normalmente temos três tipos de lançamentos:

  1. Liberação de engenharia - basicamente hot fix para algum cliente específico ou algum recurso que apenas um cliente específico solicitou imediatamente.
  2. Versão secundária - correções de erros, suporte incremental
  3. Versão principal - suporte a novos recursos etc.

Por definição, a Versão Principal deve ter a documentação relevante disponível online e offline. Nosso sistema de rastreamento garante que a documentação faça parte da lista de verificação.

Versões menores precisam de documentação apenas sobre algo novo que foi adicionado no nível de percepção do usuário. Portanto, se você incluiu outra heurística que pode reduzir a complexidade do tempo em alguns cenários específicos, pode ou não ser uma ligação significativa para colocá-la no pdf.

Versões de engenharia podem ficar sem documentação. Algumas notas de uso informal devem ser boas o suficiente para começar.

Fanatic23
fonte
0

A documentação deve estar sincronizada com o software que você está enviando para um cliente. Qualquer outra incompatibilidade vai lhe dar problemas. E se você não tem um escritor na equipe, tente contratados. Depois de encontrar um que você gosta, mantenha-o em retenção.

SnoopDougieDoug
fonte