Notation

Notation은 문서를 코드와 함께 유지 관리하려는 개발자를 위해 설계된 강력한 명령줄 인터페이스(CLI) 도구입니다. 마크다운과 같은 간단하고 보편적인 형식으로 문서를 작성하는 것과 Notion과 같은 다재다능하고 협업적인 플랫폼에 게시하는 것 사이의 격차를 해소합니다. Notation의 핵심 철학은 문서는 설명하는 코드와 함께 있어야 하고, 동일한 검토 프로세스를 거쳐야 하며, 별도의 서비스에 로그인하지 않고도 쉽게 업데이트할 수 있어야 한다는 것입니다. 이는 별도의 문서 웹사이트를 관리하거나 프론트엔드 프레임워크와 씨름하는 복잡성을 제거하고 간소화된 개발자 중심의 워크플로우를 제공합니다.

Notation을 사용함으로써 팀은 문서가 항상 코드베이스와 최신 상태를 유지하도록 할 수 있습니다. 코드가 병합될 때 해당 문서는 단일 명령으로 Notion에 게시될 수 있습니다. 이를 통해 다른 엔지니어뿐만 아니라 Notion 사용에 익숙한 제품 관리자, 디자이너 및 지원 직원과 같은 비기술 팀원도 문서에 쉽게 접근할 수 있습니다. 이 도구는 강력한 검색, AI 기능, 풍부한 서식 및 유연한 공유 옵션을 포함한 Notion의 모든 기본 기능을 활용하여 강력한 문서 시스템을 무료로 제공합니다.

Notation 사용 방법

Notation을 사용하는 것은 로컬 개발 환경을 Notion 작업 공간과 통합하는 간단한 설정 과정을 포함합니다:

1. 설치: 공식 문서에 제공된 간단한 curl 명령을 사용하여 Notation 바이너리를 로컬 컴퓨터에 설치합니다. 이렇게 하면 터미널에서 `notation` 명령을 사용할 수 있습니다.
2. 구성: `~/.notation/` 디렉토리에 `Notation.toml`이라는 구성 파일을 만듭니다. 이 파일에는 Notion API 비밀 키와 문서를 게시할 Notion의 상위 페이지 이름이 저장됩니다.
3. Notion 통합: Notion 작업 공간 내에서 새로운 내부 통합을 만들어야 합니다. 이렇게 하면 `Notation.toml` 파일에 추가할 비밀 API 키가 생성됩니다.
4. 페이지에 연결: Notion에서 상위 페이지로 지정한 페이지로 이동합니다. '연결' 메뉴를 사용하여 새로 만든 통합에 이 페이지에 대한 액세스 권한을 부여합니다.
5. 문서 작성: 프로젝트의 저장소 내에서 마크다운 파일을 사용하여 문서를 작성합니다. 파일을 디렉토리로 구성할 수 있으며, Notation은 이를 Notion의 중첩된 하위 페이지로 변환합니다.
6. 게시: 터미널에서 `notation ship --src ` 명령을 실행합니다. Notation은 마크다운 파일과 디렉토리 구조를 구문 분석한 다음 Notion 작업 공간에서 해당 페이지를 자동으로 생성하거나 업데이트합니다.

Notation의 핵심 기능

• 마크다운을 Notion으로 변환: 표준 마크다운 파일을 아름답게 서식이 지정된 Notion 페이지로 자동 변환합니다. 헤더, 목록, 코드 블록, 표, 링크 등을 지원합니다.
• 디렉토리 구조 보존: 로컬 디렉토리 구조를 Notion의 중첩된 페이지로 복제하여 복잡한 문서를 쉽게 구성할 수 있습니다.
• CLI 기반 워크플로우: 개발자의 명령줄 환경에 원활하게 통합되며 자동화된 문서 업데이트를 위해 CI/CD 파이프라인에 추가할 수 있습니다.
• 사용자 지정 페이지 메타데이터: `--title "내 페이지"` 및 `--emoji 🚀`와 같은 간단한 플래그를 사용하여 마크다운 파일에서 직접 Notion 페이지 제목과 이모티콘 아이콘을 설정할 수 있습니다.
• 상위 페이지 콘텐츠: 특별한 `intro.md` 파일을 사용하여 별도의 하위 페이지를 만드는 대신 주 상위 페이지에 직접 콘텐츠를 추가할 수 있습니다.
• Notion의 강력한 기능 활용: 게시되면 문서는 Notion의 고급 검색, 내장 AI 기능, 공동 편집 및 유연한 공유 옵션(내부, 공개 또는 웹사이트)의 이점을 누릴 수 있습니다.
• 상대 링크 처리: 마크다운 파일 간의 상대 링크를 적절한 Notion 페이지 링크로 지능적으로 변환하여 문서 내에서 원활한 탐색을 보장합니다.

Notation의 사용 사례

Notation은 다재다능하며 다양한 문서 요구에 맞게 조정할 수 있습니다:

• 내부 엔지니어링 위키: 개발팀을 위한 중앙 집중식 지식 기반을 만들고 유지 관리하며, 문서는 관련 코드 바로 옆에 있습니다.
• 공개 API 문서: 외부 개발자를 위해 명확하고 잘 구조화된 API 문서를 게시합니다. Notion 페이지는 한 번의 클릭으로 공개할 수 있습니다.
• 사용자 가이드 및 매뉴얼: 비기술적인 작성자가 (Notion을 통해) 쉽게 기여하고 개발자가 (마크다운을 통해) 쉽게 업데이트할 수 있는 사용자 대상 문서를 개발합니다.
• 프로젝트 문서: 기술 사양에서 회의록에 이르기까지 모든 프로젝트 관련 문서를 체계적으로 정리하고 프로젝트의 개발 수명 주기와 동기화합니다.
• 개인 지식 기반: 개발자는 개인 노트와 기술 참조를 관리하고 개인 Notion 공간에 게시하는 데 사용할 수 있습니다.

Notation의 장점

Notation의 주요 장점은 단순성과 개발자 우선 접근 방식입니다.

• 코드로써의 문서: 문서를 저장소에 보관함으로써 표준 개발 워크플로우의 일부로 버전 관리, 검토 및 업데이트할 수 있습니다.
• 오버헤드 감소: Docusaurus와 같은 복잡한 정적 사이트 생성기를 관리하고 배포하거나 React와 같은 프론트엔드 프레임워크를 배울 필요가 없습니다.
• 단일 진실 공급원: Notion의 문서가 저장소의 마크다운 파일을 직접 반영하도록 보장하여 콘텐츠 불일치를 방지합니다.
• 향상된 접근성: 비엔지니어가 기술 문서에 쉽게 접근하고 읽을 수 있도록 하여 더 나은 교차 기능 협업을 촉진합니다.
• 비용 효율적: 도구 자체는 무료이며 오픈 소스이며 Notion의 무료 또는 기존 계층을 활용하므로 매우 경제적인 솔루션입니다.

가격 및 플랜

Notation은 무료 오픈 소스 도구입니다. 무료로 다운로드하여 사용할 수 있습니다. 사용자는 Notion 플랜과 관련된 비용(많은 사용 사례는 Notion의 무료 플랜으로 해결 가능) 또는 Notion 페이지를 super.so와 같은 사용자 지정 도메인 웹사이트로 전환하는 데 사용할 수 있는 타사 서비스에 대한 비용만 부담하면 됩니다.