본문 바로가기
WIKI 기술 지식 베이스

TechDocs 문서

원문 보기 위키 갱신

TechDocs는 Spotify가 직접 Backstage에 내장한 자체 개발 docs-like-code 솔루션이에요. 엔지니어가 코드와 함께 있는 Markdown 파일로 문서를 작성하면, 설정을 거의 하지 않아도 Backstage에서 보기 좋은 문서 사이트를 얻을 수 있어요.

출처: 문서

본문

이게 뭔가요?

TechDocs는 Spotify가 직접 Backstage에 내장한 자체 개발 docs-like-code 솔루션이에요. 엔지니어가 코드와 함께 있는 Markdown 파일로 문서를 작성하면, 설정을 거의 하지 않아도 Backstage에서 보기 좋은 문서 사이트를 얻을 수 있어요.

오늘날 TechDocs는 5000개 이상의 문서 사이트와 하루 평균 약 10000회의 히트를 기록하며 Spotify 개발자 경험 오퍼링의 핵심 제품 중 하나가 됐어요. TechDocs에 대한 더 자세한 내용은 발표 블로그 게시물에서 읽을 수 있어요. 🎉

특징(Features)

  • 소프트웨어 환경이 어떻게 구성되어 있든 상관없이 TechDocs를 배포할 수 있어요.

  • Backstage 카탈로그의 Service 페이지에서 서비스의 기술 문서를 발견할 수 있어요.

  • Markdown만 작성하면 어떤 목적이든 문서 전용 사이트를 만들 수 있어요.

  • TechDocs Addon 프레임워크를 활용해 기본 docs-like-code 경험 위에 기능을 더할 수 있어요.

  • 방대한 MkDocs 플러그인 생태계를 탐색하고 활용해 풍부한 읽기 경험을 만들 수 있어요.

  • 문서를 검색하고 찾을 수 있어요.

프로젝트 로드맵

지금(Now)

현재 계획 없음.

다음(Next)

현재 계획 없음.

언젠가/아마도(Someday/Maybe)

  • 기술 문서 품질을 끌어올리기 위해 TechDocs에서 무엇을 할 수 있을까요? 아이디어가 많아요. 예를 들어 연관된 Trust Score가 있는 Trust Card와 문서 유지보수 알림의 자동 트리거 같은 것이죠.

  • TechDocs Addons 마켓플레이스에 기여하고 그로부터 배포하기

  • Addon: MDX (Markdown 콘텐츠에서 JSX를 사용할 수 있게 함)

  • 정적 사이트 생성기 중립적으로 갈 수 있을까?

  • Scaffolder V2와 더 나은 통합 (예: Software Templates로 문서 템플릿을 쉽게 선택·적용)

  • TechDocs의 여러 측면(예: URL, 홈페이지, 테마)을 구성할 수 있도록 하기

완료(Done)

완료된 로드맵 항목 목록은 아래 Done을 참고하세요.

지원 대상

다음 섹션은 TechDocs가 현재 지원하는 소스 코드 호스팅 제공자와 파일 저장 제공자를 보여줘요.

아래 제공자들이 어디에 사용되는지 개요를 보려면 TechDocs 아키텍처를 참고하세요.

소스 코드 호스팅 제공자

| Source Code Hosting Provider | Support Status | | GitHub | Yes ✅ | | GitHub Enterprise | Yes ✅ | | Bitbucket | Yes ✅ | | Azure DevOps | Yes ✅ | | Gerrit | Yes ✅ | | GitLab | Yes ✅ | | GitLab Enterprise | Yes ✅ | | Gitea | Yes ✅ | | AWS CodeCommit | Yes ✅ | | Harness Code | Yes ✅ |

파일 저장 제공자

| File Storage Provider | Support Status | | Local Filesystem of Backstage app | Yes ✅ | | Google Cloud Storage (GCS) | Yes ✅ | | Amazon Web Services (AWS) S3 | Yes ✅ | | Azure Blob Storage | Yes ✅ | | OpenStack Swift | Community ✅ |

더 많은 제공자를 요청하고 싶다면 연락해 주세요.

기술 스택

| Stack | Location | | Frontend Plugin | @backstage/plugin-techdocs | | Frontend Plugin Library | @backstage/plugin-techdocs-react | | Backend Plugin | @backstage/plugin-techdocs-backend | | CLI (for local development and generating docs) | @techdocs/cli | | Docker Container (for generating docs) | techdocs-container |

참여하기(Get involved)

Discord 채팅방의 #techdocs 채널에서 연락 주세요.

완료(Done)

Alpha 릴리스

Milestone

  • end to end로 사용하고 기여할 수 있는 TechDocs 알파 버전.

Beta 릴리스

Milestone

  • TechDocs 권장 구성이 대부분의 환경(CI 시스템, 클라우드 저장 솔루션, 소스 제어 시스템)을 지원함.

  • Alpha에서 Beta로 업그레이드하는 방법 안내

v1.0

TechDocs가 v1.0으로 승격됐어요! 이 변경이 패키지에 어떤 영향을 주는지 이해하려면 우리의 버전 정책을 확인하세요.

TechDocs 패키지:

  • @backstage/plugin-techdocs

  • @backstage/plugin-techdocs-backend

  • @backstage/plugin-techdocs-node

  • @techdocs/cli

TechDocs Addon 프레임워크

Backstage 1.2 릴리스에서, 읽기 시점(read-time)에 TechDocs 경험을 보강하는 TechDocs Addon 프레임워크를 도입했어요.

프레임워크 자체에 더해, 문서 품질을 끌어올리고 조직에 문서 문화를 조성하는 피드백 루프를 만드는 데 도움이 되는 ReportIssue Addon도 오픈소스로 공개했어요.

더 알아보기 (Learn more)