Documentation이 별로다 (내가 좀 덜 별로게 만들었을지도)

Source: Dev.to

The Story Behind It

기술 문서는 별로다. 우리 모두 알고 있다. 그럼에도 우리는 같은 도구들을 계속해서 사용한다. 나는 최근에 새로운 직책을 맡게 되었고, 현재 회사를 떠나기 전에 해야 할 일 중 하나가 바로 문서 지옥—즉, 내가 참여하고 있는 모든 프로젝트의 모든 부분을 문서화하는 일이다. 양이 많다.

이러한 종류의 기술 문서에 대해 일반적으로 세 가지 옵션이 있다:

• 아무도 끝까지 보지 않을 긴, 고통스러운 영상.
• README 파일을 많이 추가하는 것(지루하고 똑같이 고통스럽다).
• Notion 같은 도구를 사용하고 스니펫을 복사해 넣는 것.

다른 도구들도 있겠지만, 코드를 풍부한 텍스트와 잘 결합해 시각적으로 매력적인 편집기와 뷰어를 만들 수 있는 도구는 많이 찾지 못했다. 그래서 자연스럽게 직접 만들기로 했다…

The Product

그리 오래 걸리지 않았다—아마 전체 3~4주 정도—하지만 나는 괜찮은 문서화 솔루션을 만들었다. 이름은 Doclific이며 현재 npm 패키지로 제공되고 있다. 무료이고 오픈 소스이며, 비교적 간단한 코드베이스를 가지고 있다.

Doclific은 Git과 Notion이 아기를 낳은 모습이라고 할 수 있다. 제공하는 기능은 다음과 같다:

• 계층 구조를 가진 깔끔한 편집기.
• 요소를 빠르게 삽입할 수 있는 슬래시 명령.
• 직접 스니펫 참조(복사·붙여넣기 필요 없음).
• AI 통합—프로바이더, 모델, 키만 추가하면 된다.
• 코드베이스 안에 존재하므로 추가 비용이나 외부 문서를 유지할 필요가 없다.

My Favorite Features

코드 스니펫 요소 – 슬래시 명령으로 추가한 뒤, 특정 파일을 찾아 라인을 선택하면 매번 해당 스니펫이 표시된다. 저장소의 코드가 변경되면 다음에 Doclific을 로드할 때 자동으로 스니펫이 업데이트된다. 각 스니펫에는 파일을 열고 지정된 라인에 커서를 위치시킨 새 VS Code 창을 여는 링크도 포함돼 있어 탐색이 매우 쉽다.

AI 통합 – 이 분야 다른 제품에서는 제공되지 않는 놀라운 기능. AI에게 특정 워크플로에 대한 문서를 생성하도록 요청하면, 관련 파일을 찾아 적절한 라인을 선택하고, 설명·헤더 등을 추가한 뒤 코드 스니펫과 함께 문서에 삽입한다.

Thank You’s

Platejs 유지보수자들에게 큰 감사를 전한다. 그들은 많은 훌륭한 리치‑텍스트 편집기 컴포넌트를 제공한다.

Closing Words

이 도구에 대한 여러분의 생각을 알려 주세요. 제안이나 문제가 있으면 언제든지 연락 주세요!