당신의 집에 대한 문서 작성
(luke.hsiao.dev)주택 기술 문서 작성하기
동기 부여
- 첫 주택 소유자로서 다양한 질문에 대한 문서화된 참고 자료의 필요성 인식
- 주택에 대한 사용자 매뉴얼 및 기술 문서의 중요성 강조
추천 프레임워크
- Diátaxis 기술 문서 프레임워크 적용 고려
- 문서를 튜토리얼, 방법 안내, 기술 참조, 설명의 네 가지 유형으로 구성
변경 사항
- 주택 소유 기간 동안의 중요 변경 사항 기록을 위한 변경 사항 페이지 추가
구현
- 복잡한 웹사이트 구현 대신 간단한 바인더, 구글 문서, 유튜브 채널 등을 사용할 수 있음
- 개인적으로는 Material for Mkdocs를 사용하여 문서화 사이트 구축
디렉토리 구조
- 계약서, 다이어그램, 문서, 금융, 검사, 보험, 세금, 유틸리티 등을 포함한 예시 디렉토리 구조 제시
Mkdocs 설정
mkdocs.yml설정 예시 제공, 사이트 이름, 테마, 플러그인, 마크다운 확장 기능 포함
로컬 미리보기
Justfile을 사용하여 로컬에서 문서 미리보기를 위한 명령 실행
결론
- 문서화를 통해 가족이 필요한 정보를 쉽게 찾을 수 있는 품질 향상 경험
- 주택 가치 향상 및 다음 소유자에게 문서 전달의 중요성 강조
GN⁺의 의견
이 글에서 가장 중요한 것은 주택 소유자가 자신의 집에 대한 기술 문서를 작성하여 정보를 쉽게 찾고, 관리할 수 있는 방법을 제시했다는 점이다. 이러한 접근 방식은 주택 관리를 더 체계적이고 효율적으로 만들 수 있으며, 특히 긴급 상황이나 중요한 유지보수가 필요할 때 유용하다. 이 글은 소프트웨어 엔지니어링의 원칙을 일상 생활에 적용하는 참신한 아이디어를 제공하며, 이는 독자들에게 흥미로운 영감을 줄 수 있다.
Hacker News 의견
- 친구의 경험: 친구가 팬데믹 기간 중 집을 개조하며 생방송을 통해 사람들과 연결을 시도함. 어느 날, 욕실 벽을 허물던 중 벽 사이에서 70년대에 작성된 전기 배선과 설치 목록이 담긴 클립보드를 발견함. 클립보드 첫 페이지에는 개조 작업이 힘들고 외로울 수 있지만 계속하면 언젠가는 가치가 있다는 메모가 있었고, 이는 친구와 시청자들에게 감동을 줌.
- 집 문서화 경험: 집을 스마트 홈으로 개조하고 모든 설명서와 영상을 만들어 새 주인에게 전달했으나, 새 주인은 스마트 홈 기능을 대부분 제거하고 문서를 무시한 것으로 보임. 이후로는 집에 대한 문서화에 같은 노력을 기울이지 않기로 함.
- 시애틀 집 판매 경험: 이전 집을 개조하고 상세한 문서를 남겼으나 새 주인이 이를 무시함. 나중에 아들이 방문했을 때, 자신이 만든 벽돌 오븐이 철거된 것을 발견하고 실망함. 그럼에도 불구하고 앞으로도 집에 대한 문서화를 계속할 것임.
- 문서화의 가치: 이전 주인이 남긴 간단한 문서 덕분에 집의 역사와 유지 보수에 대한 정보를 쉽게 파악할 수 있었으며, 이는 첫 주택 구매자에게 매우 유용함.
- 위키를 통한 문서화: 모든 것을 위키에 문서화하여 유지 보수와 미래의 집 판매를 용이하게 함. 미래의 주인들도 이로 인해 감사할 것임.
- '집 책' 작성: 집과 관련된 모든 정보를 기록한 노트북을 작성하여 유지 보수에 필요한 정보를 쉽게 찾을 수 있도록 함.
- 문서화의 중요성: 가족 중 누군가가 갑작스럽게 돌아가거나 능력을 잃었을 때, 문서화된 정보가 매우 유용할 수 있음. 문서화할 때는 일반인도 이해할 수 있는 도구나 매체를 사용하는 것이 좋음.
- RV 문서화 경험: RV와 집에 대한 모든 설치물과 유지 보수에 대한 상세한 문서를 작성하여 관리를 용이하게 함.
- 아버지의 집 설계 지식: 아버지가 설계한 집에서 살고 있으며, 아버지는 집에 대한 상세한 지식을 가지고 있어 유용한 자원임.
- 문서화의 중요성 강조: 완벽함을 추구하기보다는 간단한 메모라도 남기는 것이 아무런 문서화도 없는 것보다 낫다는 의견 제시.