Gerenciamento de escrita de especificações

Simplesmente não consigo imaginar escrever software sem uma especificação. Não importa quão superficial ou alto seja, é importante explicar aos programadores quais são as funcionalidades do programa.

Mas o problema com as especificações é que ele é um cidadão de segunda classe em todo o ciclo de desenvolvimento de software; quando o desenvolvimento ganha força, é negligenciado. Porém, quando surgir uma disputa, os desenvolvedores, testadores e vendas se esforçarão para encontrar as especificações que justifiquem suas bases.

Um ou mais cenários acontecerão:

1. A especificação não pode ser recuperada, ninguém sabe onde está a especificação
2. Versões diferentes das especificações emergem de diferentes fontes; É preciso ter muita dificuldade para descobrir qual versão é a versão mais recente, ou se existe é uma versão mais recente disponível.
3. A especificação está incompleta, faltam algumas partes dos documentos a que se refere.

Portanto, o gerenciamento de especificações é importante e é igualmente importante que todos tenham apenas uma única fonte de especificações.

Como você gerencia suas especificações? Tentei fazer com que todos usassem o Google Docs, mas todos se opuseram. Todo mundo está muito apegado e apaixonado pelo Microsoft Word, o que é - na opinião deles - muito fácil de usar, muito fácil de inserir imagem, muito fácil de digitar a equação e outros enfeites.

Como convencê-los de que o MS Word é simplesmente terrível para compartilhar?

Como convencê-los de que o MS Word é simplesmente terrível para compartilhar?

Não perca seu tempo.

Primeiro. As especificações devem estar em texto simples (realmente) e sob controle do código-fonte. Use Markdown ou RST ou alguma outra ferramenta de marcação leve para produzir uma página PDF ou HTML. Texto simples.

Segundo. Pegue as várias fontes. Mesclá-los. Escreva seu próprio documento final.

Quando eles se opõem, eles têm duas opções.

1. Use o Google Docs (ou a ferramenta de controle de código-fonte) para editar sua versão.

2. Continue enviando as alterações que você edita, filtra e transforma no documento final.

Eu prefiro o 2. Alguém precisa "possuir" as especificações. E um monte de gente (no estilo wiki) leva a debates e guerras de mudanças e documentos paralelos e conversas off-line e similares.

Não acho que seja uma questão de "ferramenta", mas uma questão de "processo" (ou falta de processo).

Você provavelmente já possui um processo para liberar software (teste de unidade, teste de integração, carta de liberação, entrega etc.), também precisa implementar um processo de documentação.

• Quem vai escrever as especificações? Quem os atualizará ou manterá?
• Quem vai revisar as especificações?
• Quem vai aprovar as especificações? Arquiteto, líder de projeto, controle de qualidade?
• Como as especificações são armazenadas?
• Quem garantirá que nenhuma versão obsoleta seja usada?

É definitivamente necessário algum tipo de controle.

Ele precisa ser versionado e assinado, e esse processo precisa ser rigoroso.

Em muitos lugares, a assinatura é negligenciada, e isso leva a brigas.

O local não importa, desde que possa ser rastreado

• Sharepoint
• uma unidade compartilhada segura e com backup
• Eu já vi alguns lugares usarem o controle de código fonte !!

Mas o mais importante é que você precisa comprar de todos os envolvidos e de 1 ou 2 pessoas que é responsável por gerenciar o documento E a assinatura, por exemplo. o gerente de projeto.

O MS Word é perfeitamente adequado para criar uma especificação. Gerenciamos o nosso no SharePoint, que também lida com o controle de versão. Se você não tem o SharePoint ou outro produto de gerenciamento de documentos à mão, o Google Docs está OK (agora você pode fazer o upload de arquivos .doc / .docx sem convertê-los no formato do Google Docs). Ou, como outros sugeriram, você pode até armazená-las no sistema de controle de versão do código fonte (se as pessoas que criam as especificações tiverem acesso a esse sistema).

 > How to convince them that MS Word is just terrible for sharing?

você não pode comparar facilmente qual é a diferença de duas instâncias em um sistema de controle de versão.

Não gosto de especificações de palavras por esse motivo. Mas como é uma decisão política usar especificações de palavras, temos como primeira página "informações históricas" com essas colunas:

número da versão (relacionado à versão do produto), autor, data, descrição