Coleções e Blueprints

Coleções

Uma coleção é uma pasta de nível superior com Blueprints repetidos que compartilham um mesmo shape (o modelo do corpo). Um Framework declara cada uma no Framework.md, e o Eidos não nomeia nenhuma: specs, chapters, investigations, decisions são todas palavras do seu Framework.

Todo Framework precisa declarar primeiro uma coleção de enquadramento (os documentos soltos que dizem o que a coisa inteira é) e depois pelo menos uma coleção de unidades.

Obrigatória como declaração, nunca como barreira

Um Framework que não declara coleção de enquadramento está incompleto, e uma verificação diz isso. Mas um frame (o enquadramento) declarado e não escrito é uma lacuna a ser trazida à tona, não uma falha. O Eidos traz à tona; ele não se recusa. Mais sobre os frames →

Agrupamento

Uma coleção pode agrupar seus Blueprints em um nível de subpastas, e não mais. Ela também pode declarar uma propriedade que nomeie esse agrupamento: domain na semente software, part em book, strand em research.

Quando faz isso, três coisas decorrem:

• O valor da propriedade coincide exatamente com o nome da pasta, segundo a convenção de nomes do Framework.
• Um valor desconhecido avisa em vez de bloquear. Os agrupamentos se acumulam; o validador não é o lugar de discuti-los.
• O padrão nunca nomeia o agrupamento por você. Ele é da própria coleção.

• Directoryspecs/

  • index.md gerado — nunca edite à mão
  • Directoryplayback/ um grupo

    • watch-a-video.md
    • resume-playback.md
  • Directorychannels/ outro grupo

    • subscribe-to-a-channel.md

A folha gerada

Cada coleção carrega um index.md que lista seus Blueprints, reconstruído por inteiro pelo index. Cada linha é o summary daquele Blueprint, tal e qual: um Blueprint sem ele é sinalizado, nunca inventado. Mais sobre as folhas geradas →

Blueprints

Um Blueprint (o plano) é um arquivo markdown que define uma unidade por completo. Duas partes:

---
id: resume-playback            ← frontmatter: the agreement
title: Resume Playback
summary: Returns a viewer to the exact second they stopped.
status: In Progress
domain: playback
---

# Resume Playback                ← body: the shape

## Intent
…

O frontmatter é o acordo; o corpo é orientação. Essa linha define o que acontece quando algo está errado. As propriedades são verificadas contra o Schema do Framework. As seções do corpo são estrutura recomendada: se faltar uma, ela é anotada e oferecida, nunca recusada.

O frontmatter é gerado, não digitado

Ele é gerado por Blueprint a partir das propriedades que se aplicam à coleção daquele Blueprint. Um Blueprint novo nasce em conformidade, e uma propriedade restrita a uma coleção nunca aterrissa em outra onde não faz sentido.

Um Blueprint, uma unidade

A pergunta difícil é sempre “isto é um Blueprint ou dois?”. O Eidos te dá um teste, e ele mora no shape em vez de no padrão:

Um shape nomeia a sua própria parte estável

Todo shape tem uma parte que fica parada e uma parte que se move, e diz qual é qual. Se a parte estável mudar substancialmente, pergunte se isto não é outro Blueprint.

Na semente software a parte estável é ## Intent. Então: se o porquê muda, você tem uma spec nova. Se só os comportamentos mudam, você tem uma edição. Esse é um teste concreto que dá para aplicar numa revisão de código, que é o ponto.

Blueprints não são tarefas

A convenção que as pessoas mais tentam contornar:

Sem campos de acompanhamento de trabalho. Nada de sprint, estimate ou assignee: no momento em que você os acrescenta, um Blueprint vira uma tarefa e apodrece.

Conecte com um rastreador por meio de um link. O mesmo vale para o corpo: uma seção que descreve como você pretende construir algo captura intenção; uma seção que descreve o quanto você já avançou é acompanhamento de trabalho, e morre no mesmo calendário que o ticket. Por que isso importa →

Referenciar outros Blueprints

Referencie outros Blueprints com links, não com nomes soltos, tanto na prosa quanto nas propriedades. O id continua sendo a identidade permanente, atrás do link.

depends_on:
  - "[Watch a Video](../playback/watch-a-video.md)"

Coloque-os entre aspas no YAML: caso contrário, um [ inicial começa uma lista. E só uma raiz em Title Case carrega %20; as outras duas convenções não têm espaços.

Se um destino ainda não tem Blueprint, nomeie-o com clareza em vez de fabricar um link.

As duas maneiras pelas quais um Blueprint pode dar errado

Vale nomear as duas, porque elas falham de formas diferentes.

Ele se lê como um formulário. Todas as seções presentes, todas vazias de julgamento. O padrão é explícito quanto a isso: se um Blueprint se lê como um modelo preenchido, remodele-o até que se leia como algo que alguém escreveu. Deixe uma seção de fora quando ela genuinamente não se aplica, em vez de deixá-la cheia de nada.

Ele não tem não-objetivos. A seção Out of Scope é aquela em que o padrão mais se apoia, porque é onde o escopo de fato se sustenta, e é a primeira seção a esvaziar em silêncio quando ninguém é dono da raiz. Por quê →

A seguir

• Shapes e flavors: o modelo do corpo.
• Schema: o contrato de frontmatter.
• Escrevendo um Blueprint: do início ao fim.