Ideia principal

Um glossário de produto define palavras uma a uma: "pedido", "fatura", "cliente". Cada entrada pode estar certa, e o conjunto não ensina quase nada sobre o que o software faz. O pedido descrito sozinho continua sendo um rótulo. O mesmo pedido feito por um cliente, contendo itens, faturado em uma fatura, descreve um produto — porque os verbos carregam o que o negócio autoriza e proíbe.

Um repositório de referência que nomeia seus links se distingue assim dos três artefatos que já existiam em torno do produto: o glossário, que define sem relacionar; o esquema de banco de dados, que relaciona tabelas segundo restrições técnicas e não segundo o negócio; a documentação, que narra para um leitor humano e não expõe nenhuma estrutura interrogável.

A restrição operacional cabe numa regra de redação: nenhum link se escreve "está ligado a". Cada link carrega um verbo e as cardinalidades dos dois lados — um pedido é feito por um único cliente, ele contém pelo menos um item.

Por que isso importa

É isso que torna a descrição utilizável para além da leitura. Um link nomeado se verifica, se testa, se contradiz; "está ligado a" nunca se contradiz, logo não prova nada. É também o que permite a um agente responder a uma pergunta de comportamento sem abrir o código: a resposta está no caminho entre duas fichas.

E isso dá um critério de parada para a redação de uma ficha: enquanto os links forem vagos, a ficha não está escrita, mesmo que todos os campos estejam preenchidos.

Nuances e limites

O verbo preciso tem um custo: ele obriga a decidir casos que a definição deixava na sombra — um pedido gerado automaticamente é feito por alguém? Esse custo é justamente o que faz emergir questões de produto, mas atrasa a primeira passada.

E uma rede de links corretos não diz nada sobre a própria completude: um conjunto de fichas que só se citam entre si se fecha muito antes de ter coberto o produto.

Questões em aberto

• Até onde é preciso normalizar o vocabulário dos próprios verbos antes que dois redatores parem de nomear a mesma relação de duas formas?