Escrevendo documentação para a sua casa

Escrevendo documentação técnica da casa

Motivação

• Como proprietário de primeira viagem, reconhecer a necessidade de referências documentadas para várias dúvidas
• Enfatiza a importância de um manual do usuário e de documentação técnica para a casa

Framework recomendado

• Considerar a aplicação do framework de documentação técnica Diátaxis
• Organizar a documentação em quatro tipos: tutoriais, guias práticos, referência técnica e explicações

Mudanças

• Adicionar uma página de mudanças para registrar alterações importantes durante o período de posse da casa

Implementação

• Em vez de implementar um site complexo, é possível usar um fichário simples, Google Docs, canal no YouTube etc.
• Pessoalmente, usa Material for Mkdocs para construir um site de documentação

Estrutura de diretórios

• Apresenta um exemplo de estrutura de diretórios incluindo contrato, diagramas, documentos, finanças, inspeções, seguros, impostos, utilidades etc.

Configuração do Mkdocs

• Fornece um exemplo de configuração de mkdocs.yml, incluindo nome do site, tema, plugins e extensões Markdown

Pré-visualização local

• Executar comandos com Justfile para pré-visualizar a documentação localmente

Conclusão

• A documentação melhora a qualidade da experiência ao permitir que a família encontre facilmente as informações necessárias
• Enfatiza a importância de aumentar o valor da casa e de repassar a documentação ao próximo proprietário

Opinião do GN⁺

O ponto mais importante deste texto é mostrar que o proprietário pode criar documentação técnica da própria casa para encontrar e gerenciar informações com facilidade. Essa abordagem pode tornar a gestão da casa mais sistemática e eficiente, sendo especialmente útil em emergências ou quando uma manutenção importante é necessária. O texto oferece uma ideia original de aplicar princípios de engenharia de software à vida cotidiana, o que pode servir de inspiração interessante para os leitores.

[GN⁺]

Comentários do Hacker News

• Experiência de um amigo: durante a pandemia, um amigo reformou a casa e tentou se conectar com outras pessoas por meio de transmissões ao vivo. Um dia, enquanto derrubava a parede do banheiro, encontrou entre as paredes uma prancheta com uma lista de fiação elétrica e instalações feita nos anos 70. Na primeira página havia um bilhete dizendo que a reforma podia ser difícil e solitária, mas que, se continuasse, um dia valeria a pena, o que emocionou o amigo e os espectadores.
• Experiência de documentar a casa: transformei a casa em uma smart home e preparei todos os manuais e vídeos para entregar ao novo proprietário, mas parece que ele removeu a maior parte das funções de smart home e ignorou a documentação. Desde então, decidi não dedicar o mesmo esforço à documentação da casa.
• Experiência ao vender uma casa em Seattle: reformei a antiga casa e deixei documentação detalhada, mas o novo proprietário a ignorou. Mais tarde, quando meu filho a visitou, descobriu que o forno de tijolos que eu havia construído tinha sido demolido, o que foi decepcionante. Mesmo assim, continuarei documentando a casa no futuro.
• O valor da documentação: graças a uma documentação simples deixada pelo antigo proprietário, foi fácil entender o histórico da casa e as informações de manutenção, o que é muito útil para quem compra a primeira casa.
• Documentação por wiki: documento tudo em uma wiki para facilitar a manutenção e uma futura venda da casa. Os futuros proprietários também ficarão agradecidos por isso.
• Escrever um "livro da casa": criar um caderno com todas as informações relacionadas à casa para que seja fácil encontrar os dados necessários para a manutenção.
• A importância da documentação: se alguém da família morrer de repente ou perder a capacidade de cuidar das coisas, a informação documentada pode ser muito útil. Ao documentar, é melhor usar ferramentas ou meios que até pessoas leigas consigam entender.
• Experiência com documentação de RV: escrevi documentação detalhada sobre todas as instalações e manutenções do RV e da casa para facilitar a gestão.
• Conhecimento do meu pai sobre o projeto da casa: moro em uma casa projetada pelo meu pai, e ele tem conhecimento detalhado sobre a casa, sendo um recurso muito útil.
• Reforço da importância da documentação: em vez de buscar a perfeição, a opinião é que deixar ao menos algumas anotações simples é melhor do que não documentar nada.