Documentation

All Posts

Published on
2026년 8월 14일
이해가 병목이라는 주장과 그 순환 논리 — 설명을 생성한 쪽이 검증 대상일 때
engineering-culture code-review developer-experience documentation ai-assisted-development hacker-news
에이전트가 코드를 만드는 속도가 사람이 읽는 속도를 넘어서면 무엇이 남는가를 다룬 글이 논의를 모았습니다. 저자는 검증을 위한 이해에서 참여를 위한 이해로 목표를 옮기자고 제안하고 세 가지 장치를 내놓습니다. 그런데 댓글에서 나온 가장 강한 반론은 그 설명 자체를 모델이 쓴다면 검증이 성립하느냐는 순환 지적이었습니다. 제안된 장치 중 어느 것이 이 반론을 견디고 어느 것이 견디지 못하는지 구분해 봅니다.
Published on
2026년 8월 9일
문서 속 코드 스크린샷은 언제부터 거짓말이 되는가 — 이미지를 빌드 산출물로 만들기
documentation developer-tools cli ci automation
손으로 찍어 문서에 붙인 코드 스크린샷은 소스가 없는 산출물입니다. 코드가 바뀌어도 이미지는 그대로라 어느 순간부터 조용히 틀린 것을 보여 주기 시작합니다. goshot 같은 CLI로 이미지를 명령 한 줄에서 생성하면 문서와 함께 다시 만들 수 있게 되고, 그 순간 비밀 값 가리기와 스타일 통일까지 검토 대상으로 끌어올 수 있습니다. 무엇이 확인된 기능이고 무엇을 제가 직접 실행해 보지 않았는지도 함께 적었습니다.
Published on
2026년 8월 9일
Diátaxis를 네 개의 폴더로 오해하는 이유 — 한 문서 안에 두 모드를 섞으면 왜 무너지는가
documentation diataxis technical-writing developer-experience information-architecture
Diátaxis는 문서를 튜토리얼·하우투·레퍼런스·설명 네 종류로 나눕니다. 그런데 팀 대부분은 폴더를 네 개 만드는 것으로 적용을 끝내고, 정작 문제는 그대로 남습니다. 진짜 실패는 분류가 아니라 한 문서 안에서 네 모드를 섞을 때 일어나기 때문입니다. 왜 섞이면 무너지는지를 프레임워크가 근거로 삼는 두 축에서 되짚고, 문단 단위로 판정하는 나침반과 이번 주에 바로 돌릴 수 있는 작업 루프까지 정리했습니다.
Published on
2026년 7월 1일
고객사 문서 잘 쓰는 법 — 신뢰를 만드는 커뮤니케이션
documentation communication writing client soft-skills
제안서부터 장애보고까지, 고객사에 전달하는 문서는 곧 신뢰의 그릇입니다. 문서 유형별 작성 가이드와 독자 배려, 명확성, 톤, 그리고 문서 속 표현이 계약적 약속이 될 수 있다는 법적 함의까지 실전 예시와 체크리스트로 정리했습니다.
Published on
2026년 6월 19일
문서로 커뮤니케이션 하는 법 — 다시 읽히는 글을 쓰기
documentation writing communication async collaboration culture
문서는 협업과 인수인계의 중심이며, 끊임없이 다시 읽히기 때문에 섬세하게 써야 합니다. 목적과 결론을 먼저 두는 문서 구조, 독자 배려, 비동기 소통, 템플릿, 그리고 과한 문서화를 경계하는 법을 다룹니다.
Published on
2026년 6월 15일
워드 생산성 — 스타일, 단축키, 긴 문서 자동화
word productivity office styles shortcuts documentation
Microsoft Word의 스타일, 단축키, 목차/캡션/상호 참조, 머리글과 바닥글, 고급 찾기와 바꾸기, 검토 기능, 메일 병합을 활용해 긴 보고서를 자동화하는 실전 가이드입니다. 클릭 횟수를 줄이고 일관성을 유지하며 수십 페이지 문서를 빠르게 다루는 워크플로를 단계별로 정리했습니다.
Published on
2026년 6월 12일
글로 일하는 개발자 — 디자인 독, ADR, 그리고 설득하는 테크니컬 라이팅
technical-writing design-docs adr documentation career culture
글쓰기가 시니어 엔지니어의 레버리지인 이유부터 디자인 독과 ADR의 실전 템플릿, 리뷰 받는 문서의 기술, 나쁜 문서 비포/애프터, AI를 글쓰기에 활용하는 법과 한계까지. 코드보다 문서가 먼저 평가되는 시대의 테크니컬 라이팅 가이드입니다.
Published on
2026년 5월 14일
정적 사이트 생성기 2026 정면 비교 — Hugo · Eleventy · Astro · MkDocs · Docusaurus · Mintlify · Starlight · Nextra · VitePress · Jekyll · Zola 딥다이브
static-site ssg hugo eleventy mkdocs docusaurus mintlify starlight documentation
Next.js와 Vite 시대를 지나도 살아남은 정적 사이트 생성기들 — Hugo, Eleventy 3, Astro, MkDocs Material, Docusaurus, Mintlify, Starlight, Nextra, VitePress, Jekyll, Zola — 를 콘텐츠 사이트와 문서 사이트라는 두 축으로 정면 비교한다. 빌드 속도, 콘텐츠 모델, 검색, AI 통합, 가격, 마이그레이션 비용까지. Gatsby가 왜 무너졌고 Astro/Starlight가 왜 부상했는지, 그리고 회사 블로그 / OSS 문서 / SaaS API 문서 / 변경 로그라는 네 가지 실제 시나리오에서 어떤 도구를 골라야 하는지에 대한 정직한 결정 프레임.
Published on
2026년 4월 15일
개발자 글쓰기 완전 가이드: Design Doc, RFC, Blog, 책, 컨퍼런스 발표까지 (2025)
writing design-doc rfc tech-blog conference-talk documentation staff-plus career communication deep-dive
Staff+ 엔지니어의 80%는 코드가 아닌 글로 영향력을 행사한다. Google의 Design Doc 템플릿, Rust/Python/Node의 RFC 프로세스, Julia Evans/Dan Luu/Stratechery의 블로그 분석, O’Reilly/Manning 출간 과정, 컨퍼런스 CFP부터 본 발표까지의 실전. AI 시대 글쓰기 도구 활용, 한글 vs 영어 블로깅, Staff+ 승진 패킷 쓰는 법까지.
Published on
2026년 4월 15일
엔지니어 팀 문화 설계 완전 가이드 — Psychological Safety·DevEx·Rituals·Retrospective·Code Review·문서화·Inclusion·하이브리드까지 2025-2026년 실전편
team-culture psychological-safety devex rituals retrospective code-review documentation inclusion hybrid deep-dive guide
Google Project Aristotle이 증명한 것은 팀 성과를 좌우하는 건 스타 개발자가 아니라 문화라는 사실이다. Psychological Safety, DevEx, Ritual 설계, Retrospective, 코드 리뷰 문화, 문서화, Inclusion, 하이브리드 팀까지 600줄로 정리한다.
Published on
2026년 3월 24일
개발자를 위한 테크니컬 라이팅 가이드: RFC, ADR, 기술 블로그, API 문서 작성법
technical-writing documentation rfc adr api-docs blog-writing readme changelog communication 2026-03
개발자 글쓰기의 모든 것! RFC(Request for Comments), ADR(Architecture Decision Records), API 문서(OpenAPI), README, CHANGELOG, 기술 블로그 작성법, 다이어그램(Mermaid/PlantUML), 문서화 문화까지.
Published on
2026년 3월 16일
개발자를 위한 기술 문서 작성 완전 가이드: README부터 ADR까지
documentation technical-writing soft-skills developer api-docs adr 2026-03
README부터 API 문서, ADR까지 개발자가 알아야 할 기술 문서 작성 전략과 Diátaxis 프레임워크, 그리고 문서화 도구들을 완벽히 정리했습니다.
Published on
2026년 3월 13일
기술 보고서 작성 가이드: 구조 설계부터 데이터 시각화, 자동화까지
culture report-writing technical-writing documentation visualization 2026-03
IT 엔지니어를 위한 기술 보고서 작성 완벽 가이드. 보고서 유형별 구조 설계, 피라미드 원칙, MECE 프레임워크, 데이터 시각화 기법, 마크다운 템플릿, 자동화 도구까지 실전 노하우를 정리합니다.
Published on
2026년 3월 3일
IT엔지니어를 위한 일본어 기술 문서 작성법: 仕様書・設計書・障害報告書
japanese tech-writing specification documentation business-japanese 2026-03
일본 IT 현장에서 필수인 기술 문서(仕様書, 設計書, 障害報告書)를 작성하는 방법을 배웁니다. 각 문서의 구조, 필수 표현, 경어 사용법을 실무 예제와 함께 정리합니다.

Documentation

documentation (14)