Escrevendo a documentação da sua casa
(luke.hsiao.dev)- Quem compra a primeira casa tem dificuldade para encontrar informações como instalações, histórico de reparos, modelos de produtos e métodos de desligamento, e vê a necessidade de um manual do usuário em formato de documentação técnica também para a casa
- Se a documentação da casa for dividida, como no Diátaxis, em tutoriais, guias de como fazer, referências técnicas e explicações, fica mais fácil organizá-la conforme o tipo de pergunta
- Ao acrescentar um changelog aos quatro tipos de documentação, é possível acompanhar trabalhos e custos como reparos hidráulicos, alterações no sistema de irrigação, instalação de carpete e reformas
- A implementação pode ser simples, como um fichário escrito à mão ou um Google Doc, mas este caso monta um site de documentação pesquisável com Astro Starlight, um repositório git e Cloudflare Pages
- A família encontra as informações necessárias em um só lugar, e para o próximo proprietário, entregar apenas os fontes em Markdown já é muito melhor do que não haver registro algum
Uma casa também precisa de um manual do usuário
- No processo de ter a primeira casa, surgem com frequência momentos em que é difícil verificar rapidamente informações básicas sobre a casa
- As perguntas que de fato foram necessárias foram as seguintes
- Quando o carpete foi instalado
- Como fechar o registro geral de água
- Como o sistema de irrigação está configurado
- Onde ficam os aspersores
- Qual é o modelo da lava-louças e qual é o manual do usuário
- Por que a pressão da água está alta
- Qual empresa cuida do esgoto
- Como os circuitos elétricos da casa estão divididos
- Se há cabeamento de rede instalado
- Qual é exatamente a cor da tinta
- Qual modelo de filtro de HVAC comprar
- A maioria das perguntas não tinha resposta, ou precisou ser investigada e submetida a engenharia reversa diretamente
- Reunir essas informações cria uma base de conhecimento que a família pode consultar quando precisar, como uma boa documentação de software
Estruturando a documentação da casa com Diátaxis
- Também é possível aplicar à documentação da casa o framework de documentação técnica Diátaxis
- O Diátaxis divide a documentação em quatro modos
- Tutoriais
- Guias de como fazer
- Referência técnica
- Explicações
- Ao distribuir perguntas relacionadas à casa de acordo com esses tipos, fica mais fácil separar e encontrar “o que fazer” e “por que é assim”
Registrando o histórico da casa com um changelog
- Como apenas as quatro categorias do Diátaxis não são suficientes para abranger todo o estado da casa que muda com o tempo, foi adicionada uma página de changelog
- Mesmo que não seja possível responder a todas as perguntas do passado, é possível registrar as principais mudanças ocorridas durante o período de posse
- No changelog, são registrados itens como
- Reparos hidráulicos e seus custos
- Upgrades e alterações no sistema de irrigação
- Instalação de carpete
- Reformas
- Com isso, fica mais fácil responder a perguntas como “quando este carpete foi trocado, qual era a área necessária e quanto custou”
A implementação pode ir de um fichário a um site
- A documentação da casa não precisa necessariamente ser feita com uma stack técnica complexa
- Um fichário com anotações escritas à mão
- Google Doc
- Um canal no YouTube com vídeos curtos
- Um site pesquisável pelo celular
- Este site de documentação da casa foi implementado com Astro Starlight
- Os documentos são armazenados em um repositório git dedicado à casa, com build e deploy automáticos configurados via Cloudflare Pages
- O mesmo repositório git também é usado como local para guardar outros documentos importantes relacionados à casa
Materiais que podem ficar junto no repositório
- A estrutura de diretórios apresentada mostra o escopo dos materiais que podem entrar em um repositório de documentação da casa
- O repositório pode conter, junto, arquivos como
- Contratos e documentos de fechamento
- Plantas baixas, desenhos do escritório e diagramas como wireframes do quintal
- Arquivos do site de documentação baseado em Astro Starlight
- Documentos financeiros
- Guia para hóspedes e instruções de Wi-Fi
- Relatório de inspeção da casa
- Apólices de seguro
- Documentos de imposto predial
- Documentos relacionados ao aluguel de internet
- Dentro do site de documentação, pode haver uma estrutura com changelog, guias, introdução e documentos de referência
Valor para a família e para o próximo proprietário
- A documentação da casa se torna um único lugar onde a família encontra informações, melhorando a qualidade de vida
- A página de referência do sistema de irrigação é usada com frequência para entender como o sistema funciona
- A página de referência dos manuais do usuário reúne links para manuais em PDF ou na web de eletrodomésticos e eletrônicos
- Quando é preciso fazer a limpeza periódica da lava-louças, é possível acessar o manual em poucos cliques sem procurar novamente o número do modelo nem fazer buscas
- O guia de como fechar o registro geral de água traz tranquilidade em emergências
- O changelog facilita verificar quando determinado trabalho foi feito e quanto custou
- Mesmo que o próximo proprietário não queira uma stack técnica complexa, compartilhar apenas os arquivos plain-text Markdown usados para gerar o site já é muito melhor do que não ter registro algum
1 comentários
Comentários do Hacker News
Isso aconteceu com um amigo meu. Ele morava em uma casa antiga e, durante a pandemia, vinha fazendo projetos intermináveis de reparo; muitas vezes fazia lives de reforma à noite, enquanto trabalhava, para se conectar com as pessoas.
Um dia, ao arrancar a parede do banheiro, encontrou uma prancheta com um bilhete entre as paredes e, quando começou a ler, caiu no choro. Era uma lista de fiação e instalações escrita nos anos 1970, e na primeira página havia um recado dizendo: “reparos são difíceis e às vezes solitários, mas continue; um dia vai valer a pena”.
Num período especialmente solitário durante a pandemia, foi como encontrar exatamente no momento necessário a documentação e o incentivo deixados por alguém 50 anos antes. Foi um momento realmente bonito.
Eram correspondências calorosas e puras entre a família que tinha ido para a Califórnia e a família que havia ficado em Oklahoma, e meu tio diz que fica com a voz embargada toda vez que lê aquelas cartas.
Em Amélie, ao ouvir a notícia da morte da princesa Diana, ela deixa cair a tampa de um frasco de perfume, que bate em um azulejo da parede, revelando uma caixa de metal com objetos de infância de um menino que morara naquele apartamento décadas antes.
https://en.wikipedia.org/wiki/Am%C3%A9lie
Em Being John Malkovich, Craig encontra uma pequena porta escondida enquanto arquiva documentos e, ao rastejar por um túnel, entra na consciência do ator John Malkovich.
https://en.wikipedia.org/wiki/Being_John_Malkovich
Em A Ghost Story, uma mulher identificada como “M” conta ao marido músico, “C”, que quando era criança se mudava com frequência e costumava esconder pequenos bilhetes em cada lugar onde morava.
https://en.wikipedia.org/wiki/A_Ghost_Story
Enquanto a casa inteira estava entre a demolição e a reconstrução, deixei perfeitamente arrumado apenas o menor cômodo, de 2×2 metros, transformando-o em um refúgio; foi esse cômodo que me ajudou a manter a sanidade.
A maioria das vigas do piso tinha cedido ou apodrecido e precisou ser substituída; em certo momento, a casa parecia um espaço vazio com apenas o telhado e os escoramentos das paredes de pé. Teria sido mais rápido e melhor derrubar tudo e construir de novo, mas eu tinha decidido manter a aparência externa sem alterações visíveis, exceto por acrescentar uma janela inclinada no plano do telhado.
Depois disso ainda fiz duas grandes obras em outras casas, mas minha paixão por esse tipo de trabalho hoje está quase no fim.
Na minha casa anterior, eu tinha feito automação residencial inteligente ao longo de vários anos e deixei um fichário com instruções claras sobre tudo, recibos de upgrades, garantias, QR codes para baixar apps, mapa do terreno, planta baixa e até uma lista de contatos de prestadores de serviço.
Também gastei dezenas de horas fazendo vídeos curtos no YouTube sobre coisas como fechar o registro de água, desligar a água externa e os sprinklers, parear dispositivos, e senti uma sensação de realização por fazer uma “passagem calorosa” da casa.
Só que o novo proprietário vendeu a casa dois anos depois e, pelas fotos do anúncio, tinha arrancado a maior parte dos dispositivos de casa inteligente e feito uma reforma mal-acabada. Os vídeos no YouTube também estavam com 0 visualização, e parece muito improvável que ele tenha sequer olhado o fichário que entreguei.
Não pretendo mais dedicar tanto esforço a documentar uma casa; agora deixo apenas documentação suficiente para que dê para entender o que eu fiz.
Na prática, não compro nada anunciado como “único no mundo”. Mesmo que pareça bacana, sei que dá trabalho lidar com isso.
Vejo instalações chamativas e sofisticadas não como algo que agrega valor, mas como algo que o reduz. Porque aumentam o trabalho de remoção; uma casa com uma cozinha básica da IKEA é melhor, pois é mais fácil de substituir e, dependendo do caso, até conveniente de usar como está.
Eram centenas de páginas que incluíam não só os defeitos encontrados, mas também reparos recomendados, cronograma de manutenção contínua, fotos da localização dos registros de água, alguns vídeos e até a filmagem da inspeção por câmera da tubulação de esgoto.
Eu fui atualizando com o que acrescentei ou alterei, mas, quando chegar a hora de vender, acho que vai ser mais fácil simplesmente contratar outra inspeção. Só que não havia dispositivos inteligentes; se houvesse, talvez custasse mais.
Elas imaginam portas travando, invasores entrando ou o aquecimento ficando quente demais ou de menos por semanas durante uma viagem, e simplesmente não querem se envolver com isso.
Eu poderia viver com um simples indicador de boia, mas não havia motivo para não usar um sensor hidrostático de alta precisão, esp32, influxdb, grafana, spring, keycloak e mysql rodando na AWS.
Mas, se eu for vender a casa, provavelmente vou remover tudo, porque não quero receber ligações de suporte.
Eu também provavelmente arrancaria a maioria dos dispositivos de casa inteligente herdados ou, no mínimo, faria reflash com firmware open source.
Outro princípio importante que aprendi é que, mesmo se o Wi-Fi, o gateway, o HomeAssistant e alguns sensores morrerem, a casa precisa continuar funcionando normalmente como uma casa burra.
Há muitos relatos de que, mesmo quando a documentação é criada, ela acaba sendo abandonada, mas também há casos contrários
Comprei uma casa que estava vazia depois de um divórcio, e os dois proprietários anteriores já tinham se mudado havia alguns meses, então lidei quase só com o corretor
Dentro da casa havia um cartão de “parabéns pela casa nova”, uma garrafa de espumante e um fichário com tudo sobre a casa. Tinha plantas arquitetônicas, plantas atualizadas das partes modificadas, a localização de todos os cabos e conexões, manuais de equipamentos, contas e garantias, além de um desenho à mão da disposição das plantas do jardim e links sobre como cuidar de plantas exóticas
Graças a essa organização dos antigos proprietários, as plantas precisas economizam muito tempo sempre que faço algo com cabos ou pequenas obras, e até hoje sou grato por isso
Rotulei por cômodo por onde passavam os canos e fios, e pretendo entregar isso se algum dia vender. Não entendo por que as construtoras não fornecem por padrão esse conjunto de fotos do interior das paredes, e ele foi realmente muito útil
Tenho uma pilha de fichários para vários usos
Depois do divórcio em 2018, vendi minha casa em North Seattle. Eu a tinha comprado em 2004, trabalhava na Microsoft na época e criei meu filho naquela casa
Também construí sozinho um forno de tijolos de 8×8×8 pés para pizza e pão, aluguei uma escavadeira por uma semana e cavei ao redor da casa inteira para instalar um dreno de fundação a 12 pés de profundidade, pontos de limpeza a cada 20 pés, uma tubulação de água pex de 2 polegadas e linhas de aspersores de pvc de 1 polegada a 3 pés de profundidade. Também refiz completamente o porão
Em um fichário de 3 polegadas, deixei tudo documentado: linhas dos aspersores, drenagem da fundação, sistema de recirculação por gravidade, fiação elétrica, fotos do projeto de seis meses do forno de tijolos e até instruções de como movê-lo, se necessário
Quando vendi a casa, voei de volta para entregar pessoalmente ao novo proprietário e explicar tudo, mas ele não pareceu muito interessado nem grato
Alguns meses atrás voltei a Seattle, e meu filho de 17 anos, que nasceu naquela casa, foi até lá e perguntou se poderia dar uma olhada por fora. Eles o olharam como se fosse uma pessoa estranha, mas permitiram. Quando voltou, ele disse que tinham demolido o forno de tijolos, que eu achava que duraria mais do que eu
Eu esperava que, daqui a 100 anos, crianças comessem pizza daquele forno sem nem saber quem o tinha feito. Mesmo assim, se eu tiver uma casa de novo, vou documentar tudo outra vez; só pretendo ser mais criterioso sobre para quem vou vendê-la
Você construiu o forno, aproveitou e decidiu vender a casa; não entendo por que quer determinar como os proprietários seguintes vão usar a casa. Se queria manter o forno de pizza como um monumento a si mesmo, deveria ter ficado com a casa
Esse tipo de pensamento estagna os bairros e faz os moradores tentarem controlar a aparência e o clima da região. No fim, isso leva a regras que barram novas construções ou até definem a cor da tinta
Espaços historicamente importantes podem ser preservados, mas é problemático impor à maioria coisas pequenas que só importam a poucos. Por outro lado, lugares com significado histórico real às vezes são simplesmente deixados apodrecer
https://www.theguardian.com/us-news/2018/mar/30/rosa-parks-h...
Não dá para esperar que o novo proprietário compartilhe os interesses do anterior. Ele pode seguir uma dieta sem glúten ou não ter nenhum interesse em panificação. É difícil esperar que mantenha 64 pés quadrados do quintal como um monumento a algo sem significado para a própria família
Dá para entender o apego à casa e o desejo de que ela vá para boas mãos, mas não se deve esperar que ela não seja adaptada à nova família
Mas esse desejo não combina muito com a cultura residencial americana, que trata casas como mercadorias compradas e vendidas com frequência
Meus pais também venderam a casa deles alguns anos atrás, e meu pai costuma dizer que sente saudade dela e que o novo dono faz mudanças terríveis, mas o fato de eu ter crescido ali e vivido bons momentos não muda. Agora meu pai tem a chance de criar novas memórias com a neta na casa nova
De fato estava quebrada, mas troquei a bomba e os sensores, fiz uma boa limpeza e a aproveitamos bem por 8 anos. Quando vendemos a casa, dissemos ao comprador que, se ele não a quisesse, poderíamos negociar para levá-la para a casa nova, mas ele comprou sem responder nada
Pelo vizinho, soube que assim que se mudou ele destruiu a banheira de hidromassagem e a mandou para o aterro. É verdade que a casa era dele, mas algumas pessoas são desperdiçadoras demais
Há alguns textos dizendo que a documentação entregue não foi valorizada, mas há também outro ponto de vista. Comprei minha primeira casa, que precisava de reparos; os antigos moradores eram os pais falecidos, e o que ficou foi um saco plástico com manuais de eletrodomésticos, recibos antigos e, mais importante, uma tabela de histórico de reparos e substituições
Como estavam anotados a data, o que tinha sido atualizado e quanto custou, não precisei adivinhar a idade do ar-condicionado ou da caldeira, quando o porão tinha sido reformado, nem quanto carpete havia sido encomendado para o quarto auxiliar. Como comprador da primeira casa, isso ajudou demais, e sou muito grato
Na caldeira, anotei com marcador permanente a data de instalação e as datas de manutenção; no encanamento principal de esgoto, anotei quando foi a última limpeza, quem fez o serviço e onde estava o entupimento
Ter uma impressora de etiquetas industrial facilita esse tipo de trabalho
Parecia uma atitude muito adulta e rara, mas talvez seja mais comum do que eu imaginava
Quando construí minha casa, fiz scans Matterport antes e depois de instalar o drywall, e foi uma das melhores decisões que tomei. É como ter visão de raio X para enxergar as paredes
É útil para ver por onde passam os fios, quantos montantes há entre as janelas ao instalar uma TV, e para verificar vários problemas de elétrica, aquecimento/refrigeração e encanamento. No começo eu usava toda semana e, agora que já estou instalado, ainda uso mais ou menos uma vez a cada dois meses
Também recomendo o etiquetador de cabos Dymo Rhino 5200 e tubos termorretráteis. Se você imprimir etiquetas em tubos termorretráteis e colocá-las nos fios, nunca mais vai se confundir sobre para onde aquele cabo vai. Também é ótimo para chicotes elétricos de veículos: https://www.youtube.com/watch?v=-LcUQeTzIo4&t=66s
Mas recomendo o 5200: https://www.amazon.com/DYMO-Industrial-RHINO-Label-1755749/d... - não é link de afiliado
Esse link tem a tag de afiliado pmg097-20
O endereço sem link de afiliado é este: https://www.amazon.com/DYMO-Authentic-Industrial-RhinoPro-18...
Sempre que compro uma casa, compro um pequeno caderno Moleskine e o uso como caderno da casa. Anoto compras importantes de eletrodomésticos, datas e números de série, uma cópia local das informações dos disjuntores, datas e custos de reformas, e plantas dos cômodos com medidas
Também anoto os códigos e acabamentos das tintas por cômodo, moldura e teto; isso é muito útil quando você faz reparos em drywall e os rótulos das latas de tinta restantes estão uma bagunça
Também criei cadernos separados para mudança e compra, com dados do responsável pelo financiamento, corretor de imóveis, inspetor, compromissos, prestadores de serviço, principais datas, checklists de entrada e saída, listas de itens a guardar, descartar ou doar, despesas, documentos a entregar em órgãos públicos, além de endereços e telefones
Ter todas essas informações literalmente à mão é bastante poderoso
Tenho um RV, e ele veio com um manual grosso do chassi e outro manual para todos os equipamentos instalados de fábrica. Não sou o primeiro dono, e meu irmão, um militar bem meticuloso, deixou a documentação de todos os eletrodomésticos e dispositivos que instalou no RV
Desde que me tornei o proprietário, sou constantemente grato por essa documentação, e também documentei da mesma forma Wi‑Fi, rede, depósito de ferramentas, mesa com ajuste de altura, forno, encanamento etc.
Nos últimos três anos, mais ou menos, apliquei o mesmo princípio à casa: mantenho dois fichários grossos, um para o “chassi” da casa e outro para os equipamentos dentro dela
Anoto como redefinir a internet, como “reiniciar” o aquecedor de água, como trocar o filtro do ar-condicionado, o número do modelo dos filtros necessários e até por que o ar-condicionado não tem duto de retorno de ar, para o próximo proprietário e para mim mesmo. Também inclui o histórico de manutenção de um trecho de esgoto que desabou e foi substituído, como acessar a caixa de inspeção, por onde passam os fios dentro das paredes, disjuntores rotulados com cuidado e os códigos de tinta de cada parede
Primeiro escrevo no OneNote para tornar tudo pesquisável e depois coloco em um fichário de 3 argolas com seções por área. Não tente ferver o oceano de uma vez; faça por etapas e não leva tanto tempo, e você vai agradecer por anos. Uma casa, ao contrário de um software desenvolvido por uma equipe, também não muda tão rápido assim
É ótimo
Bastaria preencher campos online e gerar um PDF
Excelente conselho, e, se você é a pessoa da família que normalmente cuida dessas coisas, é uma boa forma de se preparar para uma morte inesperada ou incapacidade
Mas as ferramentas ou mídias usadas devem ser aquelas com as quais pessoas comuns estão familiarizadas. É preciso presumir que quem vai ler só conhece git no sentido do “git ’er done!” do Larry the Cable Guy
Para o manual da lava-louças e os parafusos de transporte, basta prendê-los com fita em cima do aparelho. Para coisas como aquecimento, uma folha de papel plastificada presa ao cano resolve
Se você gosta de digital, é melhor colocar um documento .docx em uma pasta online compartilhada; daqui a 40 anos provavelmente ainda será possível encontrar uma ferramenta para abrir e editar isso
Para algumas pessoas, criar uma stack digital é um fim em si mesmo, mas uma documentação que dure décadas é algo difícil de acreditar
Por exemplo, no quadro de distribuição da nossa casa, as etiquetas dos disjuntores estão escritas com marcador permanente, e particularidades dos eletrodomésticos ou tamanhos de filtro também ficam anotados no local. A informação fica visível exatamente onde é necessária, e não pode ser apagada nem escondida atrás de um paywall
Pessoas da área de tecnologia às vezes complicam demais as coisas
Moro na casa onde cresci. Meu pai projetou pessoalmente o segundo andar que ele ampliou.
Meu pai conhece a estrutura desta casa de um jeito que eu jamais conseguiria saber e, embora hoje more a 50 milhas de distância, ainda é um recurso incrível quando o assunto é a casa.
Alguns anos atrás, quando eu queria passar cabo cat5 até o escritório no segundo andar, ele disse: “É só furar o piso naquele canto. Há um espaço vazio que vai do segundo andar até o porão”, e era exatamente isso mesmo.
O que eu quero são as plantas que estão na cabeça do meu pai.
Agora, quando vou fazer alguma coisa, isso é muito útil porque sei exatamente como é a estrutura, e por onde passam os canos de água, os ralos e a fiação.
Provavelmente, toda vez que você pergunta algo assim, seu pai fica radiante por dentro.