Páginas e nós

A forma acompanha o peso, e o peso muda

O nó serve para o que traz uma afirmação e o argumento a favor dela; o item de lista, para o que traz uma linha; a célula, para o que traz uma palavra. A tabela serve para comparar valores ao longo das linhas, por isso um conjunto de entidades cabe em nós, e não nas linhas dela. O peso muda à medida que o assunto cresce e diminui, e por isso o conteúdo atravessa essas fronteiras nos dois sentidos: um item de lista que cresceu até ocupar vários parágrafos vira um nó, uma lista que ficou grande demais para o nome acima dela vira seções, e vários nós com uma frase cada viram uma lista.

Uma afirmação escondida dentro de um corpo não tem endereço e nunca chega à estrutura de tópicos. Ela se esconde num início de parágrafo em negrito, num item de lista que se estende por parágrafos, numa linha de tabela-catálogo ou numa segunda afirmação no mesmo bloco; um título ## digitado dentro de um corpo é a mesma coisa. Também se esconde no texto corrido, sem marca nenhuma: uma página de seções com nomes corretos e sem filhos debaixo de nenhuma delas guarda dentro de um corpo cada afirmação que faz, e o leitor que percorre a estrutura de tópicos dela não fica sabendo de nenhuma. O oposto é um título sobre uma única frase, que gasta uma linha da estrutura de tópicos e uma tela de espaço em branco com o que um item de lista dizia.

As duas falhas aparecem de fora. Numa página bem estruturada, cada afirmação de um corpo tem sua linha na estrutura de tópicos. E um corpo que, com o título coberto, parece uma nota de rodapé do próprio título é um item de lista.

O título leva exatamente o que o corpo contém

No h2, o título nomeia uma seção com uma expressão nominal de poucas palavras: o nível de cima é lido como sumário, e uma frase ali concorre com o título da própria página. Nos níveis mais fundos, o título enuncia a afirmação e o corpo a sustenta, e é isso que permite ao leitor tirar a afirmação da estrutura de tópicos e abrir o corpo só para ver o argumento. Um nó que agrupa filhos nomeia uma seção em qualquer profundidade.

As seções dão forma às afirmações. Sem elas, a página é uma fileira de afirmações em h2, do tipo que uma única passada de escrita deixa para trás, e precisa ser lida inteira para achar qualquer coisa.

O que merece uma página

Um assunto é página quando o leitor chegaria direto a ele, e bloco quando não significa nada longe do nó pai. O mesmo teste divide um assunto que cresceu: passadas umas duas dúzias de linhas na estrutura de tópicos, ou algumas telas de corpo, a página passa a ser rolada, não lida, e o sumário lateral deixa de ser um mapa; por isso uma seção que pode ser aberta sem o que vem antes é uma página à parte, e as seções que só fazem sentido em sequência ficam curtas.

Uma página, na prática

Só os títulos, que é como o leitor conhece uma página:

Regras de visto
  Quem precisa
    Cidadãos da UE não precisam
    Uma escala em trânsito conta como entrada
  Solicitação
    O formulário só é enviado pela internet
    As taxas são pagas no consulado

Os dois h2 nomeiam as seções. As quatro afirmações abaixo deles são o que a página contém, e assim o leitor tira a afirmação da estrutura de tópicos e abre um corpo só para ver o argumento. Sob o terceiro título, o corpo sustenta a afirmação e não diz nada que o título já tenha dito:

A imigração conta uma conexão na área restrita do aeroporto como entrada, então o viajante que troca de avião precisa do mesmo visto que quem sai do aeroporto. A companhia aérea cobra o visto no check-in, que é onde a falta dele costuma aparecer.

Uma página com subpáginas as recomenda em vez de listá-las

A página inicial e toda página com subpáginas abrem com o que vale a pena ler abaixo delas e trazem links para algumas páginas que os leitores procuram, mesmo as mais fundas: alguns links em destaque, não uma cópia da árvore, que o leitor já tem ao lado do texto. Uma lista com todos os filhos só cabe onde o leitor precisa escolher entre todos eles, como nas formas de instalação. Uma página assim tem seções próprias, não só uma introdução: sem elas, não tem sumário lateral e parece inacabada.

Um corpo que repete o registro do mecanismo fica desatualizado

Cada nó leva o próprio histórico, o próprio updated_at, o lugar no sumário lateral e a lista dos nós que têm link para ele. Um corpo que repete qualquer coisa disso fica desatualizado no momento em que alguém edita a página ou a estrutura dela sem atualizar aquela frase, e aí passa a informar errado.

Por isso um corpo saudável não contém nada disso: nenhum bloco que documente a própria obsolescência, porque o histórico guarda o que ele substituiu; nenhum carimbo “conferido em abril”, porque ele envelhece sozinho e não diz nada confiável sobre o conteúdo estar em dia; nenhum texto corrido que liste as seções abaixo, porque o sumário já as lista; nenhum rodapé “voltar para X”, porque os backlinks já estão na página. O que decide é de onde a frase tira sua verdade. Se tira da árvore desta página, ela sai, porque o leitor vê essa árvore, e a árvore muda sem consultar a frase. Se tira do assunto, ela fica, mesmo que hoje o número dela coincida com a árvore: o ano de fundação é conteúdo, a data de revisão é metadado, e as três leis da robótica continuam sendo três, faça esta wiki o que fizer.

Como uma referência chega a um nó

Uma referência curta, page:N ou block:N, aponta para o nó, e não para as palavras do título dele. A referência a um bloco designa uma afirmação; a referência a uma página designa um assunto. Ela não atravessa o limite de uma wiki: outra wiki é alcançada pela URL, e um link para ela se comporta como link externo, porque uma referência que atravessasse esse limite levaria a wikis que o leitor não pode abrir.