Linode의 코드로서의 문서

안녕하세요! 제 이름은 Nathan이고 Linode의 기술 문서 작성 팀의 일원입니다. 우리의 주요 업무 중 하나는 1,400개 이상의 기사가 게시되는 https://www.linode.com/docs에서 가이드 및 자습서 라이브러리에 기여하고 유지하는 것입니다. 콘텐츠의 품질을 유지하고 작성 과정에서 공동 작업을 장려하기 위해 작성 워크 플로의 코드 방법론으로 문서를 채택했습니다.

코드로서의 문서는 문서 작성에 사용하는 도구가 소프트웨어 작성에 사용되는 도구와 동일한 방법론입니다. 여기에는 다음이 포함됩니다.

• 버전 관리 소프트웨어 사용
• 일반 텍스트 문서 파일 작성
• 자동화된 테스트 실행
• 지속적 통합 및 지속적 전달 실행

Linode의 기술 문서 작성 팀은 문서 웹 사이트를 호스팅 하는 클라우드 인프라에 대한 책임을 맡아이 방법론을 확장했습니다.

왜 Docs as Code인가?

이러한 관행을 따르면 다양한 이점이 제공됩니다.

• 이러한 기술을 사용하면 기술 문서 작성 팀과 Linode의 개발 및 엔지니어링 팀 간의 긴밀한 유대를 형성하는 데 도움이 됩니다.
  
• Linode의 다른 팀은 우리 프로세스의 다양한 측면에 기여할 수 있습니다. 예를 들어 프런트 엔드 팀은 이미 작업 중인 도구를 사용하여 문서 웹 사이트의 테마 / 프레젠테이션을 업데이트하는 데 도움을 줄 수 있으며 엔지니어링 팀의 구성원은 문서 라이브러리에 대한 새로운 자동화 테스트를 작성할 수 있습니다.
  
• 우리 팀은 프로세스에 사용된 기술에 대한 가이드와 자습서를 자주 작성합니다. 이를 직접 구현하면 더 잘 이해할 수 있고 이를 설명하는 능력이 향상됩니다.
  
• 또한 Linode의 제품을 정확하게 문서화해야 하며, Linode의 코드 베이스를 검토해야 합니다. 이러한 프로젝트에 사용되는 언어와 도구에 능통하면 이를 더 잘 이해할 수 있습니다.

우리의 구현

이 방법론의 구현은 조직마다 다를 수 있으므로 프로세스에 대한 자세한 개요를 제공하고 싶습니다.

1. 저작: 우리의 기술 작가들은 Markdown에서 새로운 가이드를 작성합니다. Markdown은 일반 텍스트 파일에서 서식 있는 텍스트를 나타내는 데 사용되며 다양한 도구를 사용하여 HTML로 컴파일할 수 있습니다. Markdown은 소프트웨어 개발에서 거의 보편적으로 채택되었습니다. 예를 들어 GitHub README 파일은 Markdown으로 작성됩니다. Markdown으로 작성한다는 것은 Visual Studio Code와 같은 최신 데스크톱 편집기에서 Emacs 및 Vim에 이르기까지 원하는 모든 일반 텍스트 편집기를 사용할 수 있음을 의미합니다. 우리는 사람들이 선호하는 텍스트 편집기에 대해 강한 의견을 가지고 있으며 이러한 유연성은 더 많은 사람들이 우리 도서관에 기여하는 데 도움이 된다는 것을 알고 있습니다.
   
2. 로컬 사이트 미리보기: 라이브러리의 Markdown 파일은 최종 HTML 표현으로 컴파일됩니다. 정적 사이트 생성기. 정적 사이트는 요청 시 렌더링 되는 데이터 베이스에 의존하지 않는 미리 작성된 페이지 모음입니다 (WordPress와 같은 CMS의 경우). 이로 인해 정적 사이트는 매우 빠르게 로드됩니다. 정적 사이트 생성기는 콘텐츠 파일 (예 : Markdown)을 사용자가 지정한 테마와 결합하여 정적 사이트를 렌더링합니다.
   
   Linode의 문서 웹사이트 사용 Hugo, 이는 다음 중 하나입니다. 가장 인기 있는 정적 사이트 생성기:
   
   • Hugo는 많은 운영 시스템에서 잘 문서화된 설치 방법을 제공하므로 신입 직원이 영입될 때 문제가 없습니다. 
     
   • Hugo에는 로컬 개발 웹 서버가 포함되어 있으므로 작성자는 새 가이드를 작성하는 동안 컴퓨터에서 사이트를 렌더링 할 수 있습니다. 이 서버는 작성자가 파일을 저장할 때마다 실시간으로 다시 로드됩니다.
     
   • Hugo는 매우 빠르며 이는 우리 크기의 라이브러리에 의미 있는 요소입니다. 제 Macbook Pro는 약 3 초 만에 1400 개의 가이드를 모두 컴파일 할 수 있으며 라이브 리로딩 기능은 거의 즉각적입니다. 
     
   • Hugo의 단축 코드는 강조 표시된 메모 및 줄 번호 코드 스니펫을 포함하여 Markdown이 감당할 수 없는 기능으로 가이드를 향상시키는 데 도 도움이됩니다.
     
     
3. 콜라보레이션: 문서 라이브러리는 GitHub에서 호스팅 되는 공개 Git 저장소에 저장되며 각 작성자는이 저장소의 포크를 유지합니다. 작성자가 가이드 초안 작성을 마치면 변경 사항을 커밋하고 변경 사항을 포크로 푸시 한 다음 주 저장소에 대한 끌어오기 요청을 엽니다.
   
   우리의 글쓰기 과정은 두 명의 개별 팀원이 기술 편집을 수행한 다음 새로운 가이드 또는 가이드 업데이트에 대한 사본 편집을 수행합니다. 이러한 팀 구성원은 끌어오기 요청의 브랜치를 다운로드하고 변경 사항을 적용하고 커밋 한 다음 GitHub의 브랜치로 다시 푸시 합니다. Git은 개발을 위한 또 다른 거의 범용 도구이며 이를 사용하면 gitflow 워크 플로와 같은 공동 작업을 위한 몇 가지 표준 모범 사례를 활용할 수 있습니다.
   
   또한 GitHub의 인기는 유용한 통합 기능이 많다는 것을 의미합니다. 특히 Netlify를 사용하여 각 pull 요청에 대해 공개적으로 액세스 가능한 자동 미리 보기를 생성합니다. 우리는 종종 다른 부서의 Linodians에게 피드백을 요청해야 하며, 그들은 우리의 문서 저장소를 복제하고 랩톱에 Hugo를 설치하지 않고도 이러한 공유 가능한 Netlify 링크를 볼 수 있습니다.
   
   마지막으로 공용 저장소에서 호스팅 하면 외부 기여자에게 라이브러리가 열리므로 환영합니다.
   
4. 테스트: 끌어오기 요청이 제출되거나 업데이트될 때마다 PR의 콘텐츠에 대해 일련의 테스트가 실행됩니다. 이 테스트는 트래비스 CI로 실행되며, GitHub 통합도 제공하는 지속적 통합 서비스입니다. 이러한 테스트 중 하나라도 실패하면 끌어오기 요청이 일시적으로 병합되지 않도록 차단됩니다.
   
   • 가이드 내용의 철자와 스타일(예: 기술 용어의 적절한 대문자 사용)을 확인합니다. 우리는 Vale 을 사용하여 산문 작업을 위해 설계된 오픈 소스 linter인 이러한 작업을 수행합니다. Vale을 처음 통합했을 때 라이브러리에서 500,000개 이상의 맞춤법 오류를 보고했습니다. 조금 당황스러웠지만 이 숫자를 알고 그에 따라 조치를 취할 수 있게 되면서 콘텐츠와 새로운 출판 시스템에 대한 자신감이 크게 높아졌습니다.
     
   • 웹 사이트의 콘텐츠를 스크랩하는 오픈 소스 Python 프레임 워크인 Scrapy를 사용하여 가이드 간의 잠재적인 끊어진 링크를 확인합니다. 이 테스트는 Linode의 엔지니어링 팀원과 협력하여 작성되었습니다. Scrapy를 처음 구현할 때 마찬가지로 수정할 수 있는 여러 깨진 링크를 발견했습니다.
     
   • 또 다른 Python 스크립트는 전문 메타 데이터가 유효하고 구문 오류가 없는지 확인합니다. 깨진 전면 문제 섹션은 사이트를 구축할 때 문제를 일으킬 수 있으므로 이를 검증하면 프로덕션 웹 서버를 업데이트할 때 사이트가 렌더링 될 것임을 확신할 수 있습니다.
     
5. 게시 및 호스팅: 문서 웹 사이트 업데이트는 GitHub의 특정 이벤트에서 유발되는 스크립트 모음에 의해 자동으로 처리됩니다.
   
   • 콘텐츠가 기본 문서 저장소의 마스터 브랜치에 병합될 때마다 웹훅 알림이 Linode인 스테이징 웹 서버로 전송됩니다. 그런 다음이 스테이징 웹 서버는 GitHub에서 마스터 브랜치를 가져와서 렌더링 된 사이트의 대상으로 웹 서버의 문서 루트를 사용하여 Hugo로 사이트를 빌드합니다. 이 준비 사이트를 보고 콘텐츠가 예상대로 표시되는지 확인합니다.
     
     스테이징 서버는 처음에 워크 플로의 일부가 아니었습니다. 사고로 인해 프로덕션 사이트 업데이트 중에 CSS/스타일이 일시적으로 손상된 후 구축되었습니다. 간단히 말해, Netlify는 새 사이트 릴리스의 미리 보기를 올바르게 렌더링했지만 스타일 문제를 파악하지 못했습니다. 이는 '프로덕션'빌드 파이프라인 (CSS 및 기타 자산을 축소함) 대신 '개발' 빌드 파이프라인을 사용했기 때문입니다. 새 스테이징 서버는 프로덕션 서버와 동일한 구성으로 설정되므로 프로덕션 빌드 파이프라인도 사용하며 이와 같은 오류를 포착합니다.
     
   • 프로덕션 사이트를 업데이트하기 위해 GitHub에 새 릴리스 태그를 생성합니다. 이는 프로덕션 웹 서버로 전송되는 다른 웹훅 알림을 트리거합니다. 이 서버는 스테이징 서버와 유사한 스크립트를 실행하지만 대신 새 릴리스 태그에서 콘텐츠를 가져옵니다.
   • 게시 기능이 자동으로 발생하면 이 프로세스를 수동으로 수행할 경우 발생할 수 있는 인적 오류가 최소화됩니다. 스테이징 및 프로덕션 서버는 모두 Salt 공식을 통해 구성 관리를 받으며 소프트웨어 유지 관리 또는 업데이트가 필요할 때 인적 오류를 최소화합니다. 솔트는 Linode의 다른 인프라 프로젝트에서도 사용되므로 문서 웹 서버를 차량의 다른 부분과 함께 관리할 수 있습니다.

이 방법론을 채택한 덕분에 워크 플로를 크게 간소화할 수 있었지만 우리는 항상 이를 반복하고 개선하기 위해 노력하고 있습니다. 업데이트에 대한 제안 사항이 있으면 알려주십시오! 저는 다른 여러 팀원들처럼 Write the Docs Slack에 nmelehan으로 참여하고 있습니다. docs as code에 대해 더 많이 읽고 싶다면 Write the Docs 웹 사이트에서 Eric Holscher의 가이드를 추천합니다.