Introdução

Há diferentes formas de acessar informação :

  1. (crono)lógica, como ler página por página, linha por linha, até chegar ao fim da publicação,
  2. temática, como ir ao sumário e pular direto para a parte que lhe interessa, desde que o conteúdo esteja dividido em unidades de conteúdo significativas,
  3. transversal, como seguir uma seção de “posts relacionados” baseada em similaridade de conteúdo (definida manualmente, com tags e palavras-chave, ou aprendida por análise de tópicos por IA), ou referências cruzadas explícitas. Por exemplo, a maioria dos sites tem arquivos que listam todas as páginas que possuem uma certa tag/palavra-chave, os livros têm glossários.
  4. baseada em dicas, como apresentar uma bibliografia de publicações mais aprofundadas ou uma seção de “mais informações” ao fim do conteúdo, ou antecipar conteúdo posterior,
  5. baseada em fontes, seguindo referências (tipicamente notas de rodapé ou notas de margem) a publicações de onde a informação é extraída, principalmente para fins de verificação,
  6. recuperação de informação, isto é, o motor de busca.

Você tem que oferecer todas elas ao mesmo tempo, porque são complementares e a melhor em cada contexto depende do conhecimento inicial e das necessidades do leitor. Nenhuma dessas formas é superior às outras. Isso significa que há uma boa dose de “enchimento de palavras-chave” a fazer na sua escrita, de modo a garantir que a análise de conteúdo baseada em palavras-chave e a recuperação de informação por palavras-chave funcionem como esperado.

Um manual/documentação não é um curso, mas ater-se a uma lista árida de recursos/controles da interface e sua definição é… árido demais. Você precisa criar vínculos entre o conteúdo (o que não se resume a links HTML). No Ansel, os fluxos de trabalho começam com um objetivo e desenrolam as ferramentas para alcançá-lo. A documentação começa com as ferramentas e apresenta como e onde elas podem ser usadas. Mas esses são os dois extremos do espectro, e a realidade está sempre um pouco no meio.

De qualquer forma, o conhecimento é um grafo de rede . Você só precisa se atentar aos vínculos entre os nós. Eles são pelo menos tão importantes quanto o conteúdo.

Implementação prática no Ansel

O Ansel usa o Hugo  como seu CMS, tanto para a documentação quanto para o resto do site. A implementação prática dos princípios enunciados acima terá que lidar com os recursos centrais do Hugo.

Acesso (crono)lógico e temático

O conteúdo do Hugo é organizado em seções  que são essencialmente subpastas da pasta principal /content. As subpastas podem ser aninhadas infinitamente. O tema do site apresenta a árvore de todas as seções na barra lateral esquerda, em telas largas (desktop). Os níveis superiores de seções e subseções podem ser recolhidos/expandidos a pedido do usuário. Essa árvore fornece o sumário de nível superior, que atua como acesso temático.

Dentro das seções, a ordem relativa das páginas pode ser definida manualmente usando o parâmetro weight  nos cabeçalhos Markdown, assim :

1---
2title: Documenting Ansel
3date: 2025-10-13
4weight: 9
5---
6
7My content here

O parâmetro weight é opcional. Se não for usado, as listagens de páginas tipicamente usarão a date para ordenar o conteúdo, mas também poderiam usar a ordenação alfabética pelo título da página. Essa ordenação fornece o acesso (crono)lógico.

Dentro das páginas, se houver mais de duas seções no conteúdo (definidas por títulos de segundo nível, por exemplo <h2> em HTML ou ## em Markdown), um sumário interno será adicionado automaticamente pelo Hugo na barra lateral direita, em telas largas (desktop).

Acesso transversal

As tags podem ser definidas no site usando o parâmetro tags no cabeçalho Markdown, assim :

1---
2title: This page title
3date: 2022-12-04
4tags:
5    - color science
6    - pipeline
7---
8
9Your content

As tags são opcionais e são exibidas como links clicáveis em vários lugares no tema do site. Clicar em uma tag abre o seu arquivo, que lista todas as páginas que possuem essa tag. Isso fornece o acesso transversal.

Os autores também são incentivados a adicionar links cruzados em seu conteúdo, de páginas do site para outras páginas do site, para promover o acesso transversal. Conceitos que têm uma entrada no site devem ser transformados em links para a página que descreve cada conceito.

Baseado em dicas

Os autores são livres para adicionar uma seção Bibliografia ou Mais informações ao fim de suas páginas, com uma lista de publicações e links. Essas publicações podem ser internas ou externas ao projeto Ansel. Elas podem ser periféricas ao tópico tratado no conteúdo.

Também é possível encerrar as páginas com uma abertura para o próximo passo lógico, ao escrever sobre fluxos de trabalho ou módulos.

Baseado em fontes

O Hugo oferece suporte ao Markdown estendido, que oferece suporte a notas de rodapé . Elas são recomendadas para referenciar fontes, assim :

1The typical observer has Just Noticeable Difference (Delta E) of 2.3[^1]
2
3[^1]: Some Author, Some Publisher, _A real-world, large-sampled, study of vision parameters for white, rich, educated, American students of the Rochester Institute of Technology_, (some year). [URL](https://doi.org/xxxxx)

O Ansel ainda não se decidiu por nenhuma formatação acadêmica específica para as citações de fontes neste momento, embora o estilo de citação IEEE  pareça o mais adequado à abordagem de notas de rodapé com índice numérico.

Certifique-se de incluir o DOI  da publicação, ou ao menos alguma URL de longo prazo na qual ela possa ser recuperada agora e no futuro.

Recuperação de informação

Por enquanto, o Chantal  cuida dessa parte. O índice web é atualizado manual e periodicamente.

Diretrizes

Escrever, mesmo tecnicamente, é uma arte difícil de reduzir a um conjunto de diretrizes definidas ou melhores práticas, porque isso varia conforme o contexto. Você deve tomar cuidado para não ser mais realista que o rei. Uma boa regra prática é escrever para resolver problemas, o que significa começar perguntando a si mesmo por que e de onde o leitor chegou à página que você está escrevendo :

  1. que tipo de conhecimento supõe-se/presume-se que o leitor já tenha ?
    • o leitor idealmente deveria estar ciente desses pré-requisitos, então talvez comece com uma lista de links,
    • qualquer coisa que não esteja nesta lista deve ser definida e explicada na sua página,
  2. que tipo de tarefa o leitor está tentando concluir que o levou até esta página ?
    • ele quer um resumo rápido, um passo a passo detalhado, ou um embasamento teórico ? Você pode ter que escolher um arbitrariamente.
    • isso decidirá quais dicas você pode adicionar ao longo do texto para melhorar a rede de conhecimento,
    • isso provavelmente deve enviesar todo o ponto de vista do seu conteúdo e sua extensão/profundidade.

Uma boa forma de avaliar a qualidade da documentação é observar as perguntas mais frequentes (ou os tópicos menos compreendidos) nos fóruns. Se o tópico já está coberto mas as perguntas continuam surgindo, pode ser porque a documentação não está clara ou as páginas relevantes estão enterradas na rede e não são descobríveis o suficiente.

Translated from English by : Claude. In case of conflict, inconsistency or error, the English version shall prevail.