johanhaleby/domain-storytelling

Domain Storytelling

Uma domain story é uma imagem de um processo de negócio contada como frases: um ator faz algo com um objeto de trabalho, às vezes envolvendo outro ator. Os números nas setas carregam a ordem. Nada mais carrega.

Este skill modela a história e a renderiza. Leia references/notation.md e references/spec.md em uma única chamada antes de modelar algo não trivial. O arquivo de especificação lista cada nome de ícone.

Passos

1. Modelar a história. O rascunho é o padrão: modele o caso típico a partir do que o usuário descreveu, escolha ícones, renderize e diga quais suposições você fez. Pergunte apenas quando uma escolha alterar o modelo, em vez de decorá-lo.
2. Leia as frases de volta uma vez e pergunte qual delas é opcional ou acontece de forma diferente algumas vezes. Essas se tornam anotações. Este é o passo mais fácil de pular, e pulá-lo custa mais caro, porque a notação não tem ramificações. Uma etapa que só às vezes acontece ou carrega uma anotação ou se junta silenciosamente ao caminho feliz.
3. Execute um workshop quando o usuário solicitar um (/domain-storytelling workshop, "execute um workshop", "me entreviste sobre isso") ou quando um plano depender de um processo que ninguém documentou. Leia references/workshop.md agora. Nunca entreviste e desenhe ao mesmo tempo.
4. Escreva a especificação e a renderize conforme descrito em Renderização abaixo.
5. Aja sobre os avisos. Quando o gerador escrever algo no stderr, leia references/warnings.md agora. O gerador termina com uma linha nomeando esse arquivo, então uma leitura ignorada aparece na saída.
6. Inspecione a imagem lendo o PNG de pré-visualização que a renderização escreveu e nomeie cada arquivo escrito. Uma renderização está concluída quando não há avisos e a imagem traça limpa.

Regras que não são negociáveis

Elas vêm do método, e quebrá-las produz algo que se parece com uma domain story, mas não é.

• Cada ator aparece exatamente uma vez. Uma forma por ator, não importa em quantas frases ele apareça.
• Duas pessoas em papéis diferentes são dois atores, mesmo quando o domínio as chama pelo mesmo nome. A regra acima é sobre um ator desenhado uma vez, não sobre uma palavra desenhada uma vez. Antes de mesclar duas menções do mesmo substantivo, pergunte se uma pessoa poderia realizar ambas as etapas. Quando não puder, são atores separados, e recebem formas e nomes separados que dizem qual papel cada um desempenha aqui. Os números de sequência são o que torna isso errado em vez de apenas vago, porque eles afirmam que o ator que faz a frase 5 é o mesmo que fez a frase 2. Um único Motorista que entra na fila de uma classificação, libera uma vaga de estacionamento e depois reclama a vaga liberada diz que um motorista desistiu de uma vaga e a recebeu de volta, quando o titular que sai e o que espera na fila são dois papéis que compartilham um cargo. Uma anotação nomeando outra pessoa que poderia realizar a etapa, "um administrador pode liberar a vaga de estacionamento", é o indicador de que o ator da etapa nunca foi definido.
• Cada atividade desenha seu próprio objeto de trabalho. O mesmo pedido em três frases são três formas. Isso não é duplicação, é como a notação mostra a coisa se movendo.
• Sem condicionais, ramificações ou loops. Não há gateway, nenhum losango, nenhum "se" tracejado. Modele uma alternativa importante como uma história separada. Mantenha uma pequena variação como uma anotação.
• Uma frase começa com um ator e o número de sequência vai na primeira seta. A seta para um segundo ator carrega uma preposição, não um número.
• Frases que acontecem ao mesmo tempo compartilham um único número, e qualquer número delas pode fazê-lo. Repita o valor n entre elas na especificação. Esta é a única maneira de a notação dizer "ao mesmo tempo", já que não tem fork nem join, então use-a sempre que uma etapa não esperar pela outra. Mantenha os números separados quando uma segue genuinamente a outra, porque um número compartilhado afirma mais do que "estas duas estão relacionadas".
• Use as próprias palavras do domínio. O verbo na seta é a palavra que o especialista do domínio disse. Se você se pegar escrevendo "processa" ou "manipula", você ainda não entendeu a etapa, então pergunte. Em uma história extraída do código, a palavra do domínio é o nome da ação que uma pessoa aciona, o botão, endpoint ou comando, então um endpoint cancelar-reserva torna "cancela a reserva". Cada verbo nomeia uma ação, e duas ações diferentes em uma história recebem dois verbos diferentes. Siga o endpoint até a tela que o chama antes de nomear o ator, e nomeie o ator após os usuários dessa tela, porque um usuário de backoffice e um serviço especialista no editor admin são papéis diferentes que podem fazer coisas diferentes. Quando uma ação vizinha tem um efeito semelhante, cancelar a reserva de uma vaga de estacionamento versus remover o esperador da fila, a nota nomeia a tela e o botão, e o vizinho que não é.
• Um objeto de trabalho é um substantivo que o domínio já usa. "Fatura", "Reivindicação de vaga de estacionamento". Um e no nome é o indicador de que são dois, e a correção é escolher aquele que a atividade realmente move ou escrever duas frases compartilhando um número. A extensão é o sintoma, não a falha, então encurtar um nome composto para caber apenas o esconde.
• Diga o escopo em voz alta. Granularidade, ponto no tempo, pureza do domínio. Uma história sem eles é ambígua sobre o que ela mesmo afirma. Isso viaja na especificação e na descrição do Egon, em vez de na imagem, porque esses três termos são o método falando com o modelador, e um leitor da imagem não pode decodificá-los.

Mostrando onde uma mudança cai

Quando o objetivo da história é o que uma mudança faz em um processo, marque as frases que ela toca com "changed": true e diga isso na descrição. Uma imagem com o delta marcado geralmente é melhor que duas imagens que o leitor precisa comparar visualmente. Desenhe uma história AS-IS e uma TO-BE quando a forma do processo mudou, ou seja, etapas se moveram entre atores ou desapareceram, em vez de quando as etapas permaneceram no lugar e apenas seu conteúdo mudou.

Quando a mudança decide quem recebe algo, uma oferta, uma prioridade ou uma vez, desenhe o contraste: a pessoa que perde e a pessoa que ganha, como dois atores no mesmo papel nomeados por sua posição ("Primeiro na fila", "Segundo na fila"). Termine na frase que nomeia qual deles recebeu. Com um ator nesse papel, uma regra que passa por cima de alguém desenha exatamente como uma regra que não faz nada.

Uma história extraída do código em vez de uma pessoa é uma leitura desse código. Diga isso ao lado da imagem, para que um leitor saiba que não foi verificada com ninguém que faz o trabalho. Antes de desenhar uma frase alterada, leia a proteção que decide quando o novo comportamento se aplica: o estado que requer e o evento que o executa. Desenhe esse evento como a frase anterior à mudança, e coloque um estado que toda a história mantém, como "o motorista que sai ainda está estacionado lá", na descrição. Uma nota como "na próxima vez que a fila for consultada" não nomeia nenhum ator, e é o indicador de que o gatilho nunca foi encontrado.

Quantas histórias

• Uma história por alternativa importante. O caminho feliz primeiro.
• AS-IS e TO-BE são sempre histórias separadas, nunca uma única imagem.
• Uma visão geral grosseira mais uma história detalhada para a etapa que importa, quando o processo é grande.
• Divida em aproximadamente quinze frases, seja qual for o resto. Uma imagem ampla e ocupada é o método dizendo que a história é grande demais.

Nomeie um conjunto para que seja lido como um conjunto: Reembolso - AS-IS, Reembolso - TO-BE.

Renderização

Escreva uma especificação como JSON, então execute o gerador a partir do diretório que contém este SKILL.md:

python3 scripts/story2egn.py path/to/story.json --preview <diretório scratch>

Apenas biblioteca padrão. Ele escreve dois arquivos ao lado da especificação, ou em --out-dir, e --preview adiciona <Título>.png em um diretório próprio, então uma chamada renderiza a história e devolve a imagem para leitura. Aponte --preview para um diretório scratch ou temporário, longe dos arquivos que serão enviados. O PNG vem do rsvg-convert, cairosvg ou inkscape quando um está instalado e do macOS Quick Look caso contrário. --help lista os outros formatos e --date.

• <Título>.egn.svg é a imagem e o modelo editável em um arquivo. Abre em qualquer visualizador SVG e importa em https://egon.io. Egon lê o título da história de volta do nome do arquivo, então o título na especificação decide o nome do arquivo.
• <Título>.board.svg é a mesma imagem para uma página. Cada ator, objeto de trabalho, atividade e nota está em um grupo marcado com as etapas a que pertence, e carrega seu próprio modo escuro. scripts/story-board.js pode escurecer, circular ou cortar para uma etapa. Um quadro desenhado à mão no egon.io não tem marcações, então permanece uma imagem simples.

Sempre informe ao usuário os caminhos que foram escritos. Mostre as imagens inline se o host puder exibir imagens, caso contrário, os caminhos são a entrega. Nunca diga que uma história foi produzida sem nomear seu arquivo.

Lendo uma história de volta

Arquivos .egn, .egn.svg e .dst legados são lidos pelo skill irmão egn-to-text. Use-o em vez de analisá-los aqui.