Doctective

Doctective는 완고한 문제 하나를 중심으로 만들어진 개발자 도구다. 코드는 끊임없이 바뀌는데 문서는 그렇지 않다는 점이다. 누군가 함수 이름을 바꾸거나 설정 플래그를 고치거나 endpoint를 다시 쓰면, 그 동작을 설명하는 문서는 조용히 낡는다. 누군가 오후 한나절을 날리기 전까지는 아무도 눈치채지 못한다.

Doctective는 그 어긋남을 지켜본다. 코드베이스와 문서를 인덱싱한 뒤 둘 사이에 의미적 연결을 그린다. 어떤 pull request가 문서가 참조하는 코드를 건드리면, 도구는 영향을 받는 페이지를 표시하고 제안된 업데이트를 담은 동반 PR을 작성한다. 승인은 여전히 전부 직접 하지만, 첫 번째 패스는 이미 끝나 있다.

범위는 분명히 해 두자. Doctective는 소스 코드와 문서를 읽으므로 개발 워크플로에 살고, 마케팅 사이트나 고객용 위키에는 살지 않는다. 팀이 GitHub을 쓰지 않는다면, 아마 대상 독자가 아니다.

그러면 문서가 엉망인 사람에게만 도움이 된다는 뜻일까. 꼭 그렇지는 않다. 규율 있는 팀도 리팩터링 한 번에 옛 동작을 설명하는 페이지 세 장을 남기곤 한다.

시작하기

1. doctective.app에 접속해 Get Started를 클릭하면 GitHub 연결이 시작된다.
2. Doctective GitHub App을 설치하고 감시하려는 저장소에 대한 접근을 허용한다.
3. 인덱싱할 repo를 고른다. Doctective는 곧바로 코드와 문서 사이에 의미적 연결을 만들기 시작한다.
4. 평소처럼 pull request를 연다. 문서화된 코드를 건드리면 Doctective가 그 PR에 댓글을 달고, 문서 편집 제안을 담은 동반 PR을 연다.
5. 제안된 변경을 검토하고 필요하면 문구를 다듬은 뒤, 남기고 싶은 것을 병합한다.