Documentação do LAC — diretrizes de autoria e comunicação

1. Contexto e alcance

O autor precisa produzir documentação com esforço viável e comunicar-se com leitores, colaboradores e clientes. Um formato simples de preparar pode exigir do destinatário mais esforço para abrir, localizar e compreender as informações.

Problema a resolver: evitar entregas difíceis de ler, escolhas de ferramentas sem finalidade clara e versões paralelas que divergem.

Resultado esperado: cada documento informa sua finalidade, público, fonte oficial, versão e forma de entrega; o leitor consegue acessá-lo e utilizá-lo no contexto previsto.

Aplica-se a páginas de conhecimento, especificações, modelos, pareceres, instruções, registros e documentos de comunicação. Atende autor, colaborador, revisor, mantenedor e destinatário da entrega. Não impõe migração imediata de documentos existentes.

Conhecimento necessário: organização textual e uso da ferramenta escolhida. Edição direta de páginas exige HTML e, quando aplicável, CSS e JavaScript. O preparo visual no LibreOffice permite iniciar documentos simples sem escrever tags.

2. Escolher a forma de entrega

Comece pela tarefa de quem recebe. Depois escolha o formato e a ferramenta de preparo.

O que o destinatário precisa fazer?

Orientação local baseada nesta diretriz. A seleção não grava dados, não converte arquivos e não publica conteúdo.

3. Ferramentas e formatos

Matriz de referência para o trabalho do autor
Finalidade	Preparo	Fonte e entrega
Páginas, modelos, especificações e pareceres do LAC	Sublime Text e modelos HTML; apoio de IA revisado pelo autor.	HTML como fonte quando mantido diretamente. Entrega por navegador, preferencialmente com link publicado.
Documento simples com edição visual	LibreOffice Writer ou Writer/Web.	Escolher ODT como fonte e HTML/PDF derivados; ou HTML como fonte se a edição ocorrer no Writer/Web. Conferir a exportação.
Documento editável para cliente ou instituição	LibreOffice Writer.	ODT ou DOCX, conforme combinado. DOC quando expressamente necessário; conferir compatibilidade.
Instruções junto ao código e README	Editor de texto com pré-visualização quando disponível.	Markdown como fonte; leitura renderizada na plataforma. Gerar HTML para público geral quando necessário.
Análise computacional	Jupyter, com código, explicações e resultados.	IPYNB como fonte do experimento; HTML para divulgação. Registrar dados, dependências e instruções para reprodução.
Dados e registros estruturados	LibreOffice Calc ou editor apropriado.	CSV, JSON ou planilha conforme estrutura e necessidade. Documentar campos e significado.
Edição de distribuição ou impressão	Exportação da fonte; impressão pelo navegador ou LibreOffice.	PDF derivado, identificado com versão/data. Atualizar a fonte antes de gerar nova edição.

Word instalado não é requisito deste padrão. LibreOffice é a referência de escritório do autor. Sublime é a ferramenta habitual de código; VS Code/VSCodium podem ser usados conforme necessidade. A matriz orienta o trabalho e não obriga novas instalações.

4. Regras de trabalho

D01 · Apresentação orientada ao leitor

Usar HTML como apresentação preferencial no LAC. Definir hierarquia visual, contexto, navegação e legibilidade. Não presumir que um arquivo Markdown isolado será renderizado pelo dispositivo do destinatário.

D02 · Uma fonte oficial por documento

Identificar o arquivo mantido como autoridade para o conteúdo. HTML gerado de Markdown, PDF exportado de ODT e outros derivados recebem identificação da fonte e de sua versão. Não editar manualmente duas cópias como se ambas fossem oficiais.

Quando um cliente devolve uma cópia editada, revisar as alterações e incorporá-las à fonte escolhida. Preservar originais e histórico conforme as regras de versionamento aplicáveis.

D03 · Formato compatível com o canal

Para público geral, preferir link HTML acessível pelo navegador. Para edição, entregar formato combinado; para registro estável, PDF; para repositório, Markdown quando adequado. Respeitar o formato obrigatório da plataforma de destino.

Um arquivo HTML anexo não oferece necessariamente a mesma facilidade de acesso que uma página publicada. Para leitura offline, conferir arquivos auxiliares, caminhos e instruções de abertura.

D04 · Estrutura e complexidade proporcionais

Usar modelos reutilizáveis adequados ao tipo de documento. Incluir interação apenas quando facilitar a tarefa. Um parecer pode ser HTML simples; não precisa de SPA ou JavaScript para ser legível.

D05 · Conversões conferidas

Depois de exportar, verificar títulos, parágrafos, listas, tabelas, imagens e links. Testar impressão quando fizer parte da entrega. Não salvar páginas complexas do LAC em editor visual sem verificar a preservação de CSS, scripts e navegação; trabalhar em cópia ao avaliar uma conversão.

D06 · Acesso e confidencialidade explícitos

HTML não significa conteúdo público. Antes de disponibilizar um parecer, confirmar quem pode recebê-lo e qual meio atende à restrição de acesso. Um endereço pouco divulgado não constitui controle de acesso.

D07 · Assistência da IA sob responsabilidade humana

A IA pode apoiar organização, redação, conversão e verificações. O responsável humano confere fontes, significado, recomendações e evidências. Distinguir análise sugerida, teste executado, revisão humana e aceitação; registrar limites relevantes do apoio utilizado.

5. Estrutura mínima da documentação

Todo documento deve permitir identificar: título, finalidade, público, objeto, responsável, versão/data e estado. Informar fontes e limites quando sustentarem sua interpretação. Documentos curtos podem registrar esses itens em poucos parágrafos.

Tipo	Sequência de leitura recomendada
Parecer	Contexto → entrada e versão → recorte → critérios e método → conclusão → evidências e achados → recomendações → limites e devolutiva.
Especificação	Problema e resultado esperado → pessoas e contexto → escopo e restrições → requisitos e regras → modelos e interfaces → critérios de aceitação → rastreabilidade e pendências.
Página de conhecimento	Referente e finalidade → contexto e público → conhecimentos prévios → conteúdo e relações → exemplos e como usar → fontes e limites.
Instrução ou README	O que é e para quem → pré-requisitos → passos → exemplo → resultado esperado → dificuldades conhecidas e ajuda.

A estrutura mínima não exige repetir seções sem conteúdo nem transformar toda página em relatório extenso. Os modelos devem favorecer compreensão e manutenção.

6. Preparar e disponibilizar

Delimitar: identificar leitor, tarefa, conteúdo de entrada, recorte e entrega esperada.
Escolher: definir fonte oficial, ferramenta e formatos derivados.
Produzir: escrever com modelo apropriado; registrar fontes e distinguir fatos de propostas.
Revisar: conferir significado, consistência e apresentação no formato de destino.
Disponibilizar: conferir acesso, versão, links e abertura; registrar a entrega ou publicação efetivamente realizada.
Atualizar: alterar a fonte, gerar os derivados e manter a correspondência entre versões.

Essas atividades podem ser iterativas. O término exige conteúdo revisto e entrega conferida nas condições combinadas; produzir o arquivo não equivale a publicar nem obter aceitação do destinatário.

7. Exemplos de aplicação

Parecer para um cliente

Preparar o parecer em um modelo HTML do LAC. Apresentar contexto e recorte antes da avaliação. Entregar por meio acordado, com PDF se necessário para arquivamento. Fonte oficial: HTML; PDF identificado como derivado. Restringir acesso quando houver informações do cliente.

Documento iniciado no LibreOffice

Preparar visualmente um documento simples em ODT e exportar para HTML. Conferir o resultado no Firefox. Mantendo ODT como fonte, realizar futuras alterações nele e refazer a exportação. Se passar a manter o HTML diretamente, registrar a mudança da fonte oficial e identificar o ODT como antecedente.

README de software e experimento computacional

Manter README em Markdown quando esse for o fluxo do repositório. Em um notebook, combinar explicações com código e resultados; fornecer instruções de reprodução e exportar a leitura para HTML quando destinado a quem não usa notebooks.

8. Conferir a entrega

Use esta lista como apoio de revisão, registrando evidências no trabalho correspondente. Ela não é um formulário de aprovação automática.

O leitor identifica o assunto, a finalidade e o que pode fazer com o documento?
Objeto de entrada, recorte e limites estão claros quando há análise ou parecer?
Fonte oficial, versão, data e estado estão identificados?
Títulos, tabelas, links e imagens permanecem legíveis no formato entregue?
A página pode ser lida em tela pequena e ampliada sem perder conteúdo essencial?
Controles têm rótulos, foco visível e operação por teclado quando há interação?
O destinatário consegue abrir o documento com os recursos previstos?
Permissões e confidencialidade correspondem à entrega combinada?
Derivados correspondem à versão da fonte e pendências estão explícitas?

9. Responsabilidades e localização

Autor do documento: Define conteúdo, contexto, fonte e versão; prepara a entrega.
Revisor: Examina critérios acordados e registra achados, evidências e limites.
Responsável editorial ou pela aceitação: Decide sobre adequação e disponibilização no escopo de sua responsabilidade.
Mantenedor: Confere arquivos, links e derivados após atualização e publicação.

Uma pessoa pode acumular papéis. O registro deve esclarecer quem efetivamente revisou, aceitou ou publicou; não atribuir aprovação a uma função ainda não exercida.

Caminho definido para esta diretriz: governanca/diretrizes/documentacao_lac.html. Localização definida pelo autor em 03/11/2026. Sua função predominante é orientar decisões e práticas de documentação, justificando a área de Governança. A subpasta diretrizes/ é uma organização interna; não cria nova área-raiz. A integração ao índice da Governança e a existência dos destinos no site ainda precisam ser verificadas.

Distinção física: esta diretriz orienta escolhas e responsabilidades em Governança; documentacao/ pode reunir documentos que explicam e registram o sistema, conforme suas regras. Especificações, registros e pareceres permanecem associados à área, projeto ou demanda a que pertencem. Não mover toda a documentação para uma única pasta por causa do formato.

10. Fontes, estado e evolução

Deliberações desta elaboração: conversa com Walter em 03/11/2026 sobre preparo, leitura, Markdown, HTML, LibreOffice e comunicação com o mercado. Fundamentam a proposta de ferramentas e formatos.
Regra da raiz consultada: Regras da estrutura da raiz do LAC, exemplar regras_estrutura_raiz_lac(20261103-153329).html fornecido pelo autor. Sustenta o uso da área existente de Governança, sem nova área-raiz.
Regra de integridade consultada: Regras de integridade entre pastas e arquivos do LAC, exemplar regras_integridade_pastas_arquivos_lac(10).html fornecido pelo autor. Sustenta localização pela função predominante, nomeação, breadcrumbs, ligação ao índice, ambiente e estado explícitos.

Ambiente: desenvolvimento. Estado: em revisão para apreciação do autor. Não há aprovação formal, publicação no site nem atualização de índice registrada nesta entrega. Os links de integração são destinos previstos para a instalação no caminho definido; sua existência no site não foi verificada.

Evolução: registrar alterações de diretriz, justificativa, responsável e documentos afetados. Aplicar gradualmente aos novos trabalhos; avaliar migrações individualmente.

Versão	Data	Alteração
1.0	03/11/2026	Primeira elaboração com matriz de formatos, sete diretrizes, estrutura documental, responsabilidades e conferência de entrega.
1.1	03/11/2026	Caminho definido em governanca/diretrizes; breadcrumbs físico e semântico; ambiente e estado explícitos; referências às duas regras fornecidas pelo autor.

Documentar para compreender e comunicar