Capítulo 14 — Documentação simples
Mapa da aula
Aula 14 publicada. Mapa, exemplo, EX053.
flowchart TD
N0["14.1 Verbetes do dicionário"]
N1["14.2 Um procedimento curto"]
N2["14.3 Testando os documentos"]
N3["14.4 Encontrando os documentos"]
N0 --> N1 --> N2 --> N3
N3 --> EX["Exemplo resolvido"]
EX --> Q["Exercício EX053"]
Desenho lógico
flowchart LR
N0["14.1 Verbetes do dicionário"]
N1["14.2 Um procedimento curto"]
N2["14.3 Testando os documentos"]
N3["14.4 Encontrando os documentos"]
N0 --> N1 --> N2 --> N3 --> Q["EX053"]
[14.1 Verbetes do dicionário]
|
v
[14.2 Um procedimento curto]
|
v
[14.3 Testando os documentos]
|
v
[14.4 Encontrando os documentos]
|
v
[Exemplo resolvido] --> [Exercício EX053]
Objetivos de aprendizagem
Você vai (1) escrever um verbete de dicionário de dados; (2) escrever um procedimento curto; (3) manter os documentos fáceis de encontrar.
14.1 Verbetes do dicionário
Marta escreve os verbetes do dicionário para o arquivo de contagens de passageiros. Para cada campo, registra o nome, o significado em palavras simples, o formato, os valores permitidos e a origem. Para embarques, escreve: número de passageiros que sobem durante a viagem, número inteiro de zero a cento e vinte, registrado pelos sensores das portas. Ela confere cada verbete com o Sr. Hughes. Observa que definições claras impedem que as pessoas adivinhem o significado dos campos quando montam relatórios. O Sr. Hughes sugere duas pequenas correções, que ela faz no mesmo dia antes de publicar o dicionário.
14.2 Um procedimento curto
Marta escreve um procedimento para o arquivo mensal da autoridade: executar a verificação de contagens ausentes, corrigir ou anotar os problemas, preparar o arquivo a partir do modelo, conferir os totais com o relatório mensal, obter a aprovação do Sr. Hughes e enviar pelo portal. Cada passo é numerado e diz quem o executa. Ela mantém a linguagem simples e acrescenta o que fazer se o portal estiver fora do ar, o que aconteceu uma vez durante o curso. O Sr. Hughes aprova o procedimento e pede que ele seja usado todo mês por quem preparar o arquivo.
14.3 Testando os documentos
Marta pede a uma colega de turma que prepare um arquivo de treino para a autoridade usando apenas seu procedimento. A colega empaca na conferência dos totais, porque o procedimento não diz com qual relatório comparar. Marta acrescenta o nome e o local do relatório. A colega então conclui sem ajuda. O Sr. Osei explica que testar os documentos com alguém novo mostra onde faltam passos que parecem óbvios para quem escreveu. Marta registra a mudança e o motivo na seção de histórico do procedimento, para que os leitores futuros vejam como o documento melhorou com o tempo.
14.4 Encontrando os documentos
Marta guarda o dicionário, os procedimentos e os scripts em uma única pasta compartilhada, com uma página de sumário que lista cada documento, seu dono e a data da última conferência. O Sr. Hughes pede à equipe que use a página de sumário em vez de procurar nos e-mails. Marta aprende que os documentos só ajudam se as pessoas conseguem encontrá-los depressa, e que as datas mostram se um documento provavelmente ainda está correto. Ela confere a página de sumário a cada trimestre durante o estágio, atualiza as datas dos documentos revisados e sinaliza os que não consegue confirmar.
Exemplo resolvido
Marta escreve verbetes do dicionário conferidos com o Sr. Hughes e um procedimento numerado para o arquivo da autoridade, com uma alternativa para o portal fora do ar, testa-o com uma colega que encontra a falta do nome de um relatório e guarda os documentos com uma página de sumário datada.
Caso sintético. Os documentos são sintéticos.
Erros e limites
Procedimentos testados apenas por quem os escreveu deixam passar passos que parecem óbvios.
Exercícios
- EX053 — Definição de embarques. Como os embarques são definidos? Rubrica: 3 = passageiros que sobem, número inteiro de 0 a 120, registrado pelos sensores das portas;; 2 = parcialmente correto;; 1 = parcial;; 0 = nenhuma.
- EX054 — Lacuna no procedimento. Onde a colega empacou? Rubrica: 3 = na conferência dos totais;; 2 = parcialmente correto;; 1 = vago;; 0 = nenhuma.
- EX055 — Página de sumário. O que a página de sumário lista? Rubrica: 3 = cada documento, seu dono e a data da última conferência;; 2 = todos;; 1 = alguns;; 0 = nenhuma.
- EX056 — Alternativa ao portal. Que caso extra o procedimento cobriu? Rubrica: 3 = o portal fora do ar;; 2 = parcialmente correto;; 1 = vago;; 0 = nenhuma.
Continue estudando — aula 14 (capítulo 14 de 18)
← Capítulo 13 · Índice das aulas · Capítulo 15 →
Continue para a próxima aula já escrita.