개발자를 위한 문서 워크플로를 자동화하는 방법

이 튜토리얼을 최대한 활용하려면 Git, GitHub, Linux 및 명령줄에 익숙해야 합니다.

고품질 문서에 관심을 가져야 하는 이유는 무엇입니까?

많은 팀이 문서 작성 에 어려움을 겪고 있습니다. 프레임워크를 확인하려고 하면 문서가 오래되었거나 명확하지 않은 경우가 많습니다. 이것은 팀 구성원이 기능을 추가하려고 할 때 내부 좌절로 이어질 수 있지만 문서가 좋지 않아 현재 기능이 어떻게 작동하는지 이해하지 못합니다. 이로 인해 작업 시간이 비생산적일 수 있습니다.

문서가 부실하면 좋은 고객 경험도 손상됩니다. Ask Your Developer 의 저자이자 Twilio의 설립자인 Jeff Lawson에 따르면 API를 제품으로 판매하는 경우 문서는 기술 이해 관계자를 위한 궁극적인 광고입니다 . IBM은 문서의 중요성에 대한 연구를 수행했으며 응답자의 90%는 제품 문서의 품질을 기반으로 구매 결정을 내렸다고 인정했습니다.

좋은 문서를 작성하는 것은 개발자와 고객 경험에 중요합니다.

문서화가 그렇게 중요하다면 엔지니어링 팀이 문서의 우선 순위를 낮추는 이유는 무엇입니까?

문서를 작성하면 개발자가 "흐름"에서 벗어날 수 있습니다. 문서 는 종종 기본 코드 기반 외부에 있으며 찾고 업데이트하는 것이 번거롭습니다. Excel 스프레드시트나 독점 CMS에 넣는 것은 드문 일이 아닙니다.

문서를 자동화하고 문서 워크플로를 개선하면 이 문제가 해결됩니다.

높은 수준에서 문서 자동화

문서 자동화 란 무엇을 의미합니까? 이는 일반적인 소프트웨어 개발 관행을 채택하는 것을 의미합니다. 문서를 자동화하면 다음과 같은 이점이 있습니다.

• Markdown으로 문서 작성
• CI/CD(지속적 통합 및 지속적 배포) 파이프라인을 사용하여 오류 수정 및 업데이트 배포와 같은 작업을 실행합니다(이 자습서에서는 GitHub 작업을 강조 표시할 예정임).
• 스타일 가이드를 시행하고 일반적인 문법 실수를 수정하기 위해 Vale와 같은 도구를 구현합니다.

스타일 가이드

Vale 및 GitHub Actions와 같은 도구를 사용하여 스타일 가이드를 자동화하기 전에 잠시 시간을 내어 스타일 가이드가 정확히 무엇인지 정의해 보겠습니다.

문서를 작성할 때 무언가가 약간 어긋난 것처럼 보이는 느낌을 알고 계십니까? 귀하의 설명은 문서의 나머지 부분에 맞지 않지만 왜 잘못된 것인지 설명할 수 없습니다. 글은 개념을 설명하지만 적합하지 않은 것 같습니다.

이러한 느낌을 받을 때 목소리와 톤이 꺼져 있을 수 있습니다 . 음성과 어조를 다듬는 것은 QA, 엔지니어링 및 제품 팀에서 편집한 문서를 개발하는 경우에도 글을 응집력 있게 만드는 방법입니다. 아래는 Torrey Podmajersky 의 UX를 위한 전략적 작성 책에서 가져온 시내 버스 애플리케이션 TAPP의 예시 스타일 가이드입니다.

TAPP은 대중교통 어플리케이션입니다(버스 및 기차용). 테이블의 헤더는 효율적이고 신뢰할 수 있으며 접근 가능한 기업으로서 TAPP의 가치를 알립니다. 표의 왼쪽에는 스타일 가이드에서 다루는 다양한 부분(개념, 어휘, 장황함, 문법, 구두점)이 나열되어 있습니다.

함께 스타일 가이드 를 만듭니다. 머리글은 값을 소개하고 표의 왼쪽은 모든 서면 자료에서 찾을 수 있는 다양한 구성요소(어휘, 문법, 구두점)를 보여줍니다. 이 스타일 가이드의 장점은 엔지니어와 카피라이터가 Tapp의 브랜드 아이덴티티를 홍보하기 위해 사용할 대문자와 구두점을 명확하게 알 수 있다는 것입니다.

테크니컬 라이팅 스타일 가이드

모든 스타일 가이드가 테이블에 있는 것은 아닙니다. Microsoft는 두문자어부터 편견 없는 커뮤니케이션, 챗봇에 이르기까지 모든 것을 포괄하는 포괄적인 가이드 역할을 하는 전체 웹사이트를 보유하고 있습니다. 물론 Microsoft만이 스타일 가이드를 가지고 있는 유일한 회사는 아닙니다. 구글에도 하나 있다.

스타일 가이드의 문제

스타일 가이드는 문서화에 대해 진지한 회사를 위한 훌륭한 출발점입니다. 그들은 개발자들이 추진하고 있는 주요 기능에 대해 정확히 어떻게 작성해야 하는지에 대해 가질 수 있는 많은 혼란을 해결합니다.

스타일 가이드의 문제는 작성 과정에 마찰을 더한다는 것입니다. 저를 포함한 많은 작가들은 질문이 있을 때마다 글을 쉬지 않고 스타일 가이드를 살펴봅니다. 때때로 스타일 가이드는 번거롭고 참조하기 너무 어렵습니다. 예를 들어, Microsoft 스타일 가이드는 천 페이지가 넘습니다!

문서용 린터 및 CI/CD

프로그래머라면 린터에 익숙할 것입니다. Linters는 팀에 코딩 표준을 적용 하는 이상적인 방법입니다. 문서화도 마찬가지입니다. 린터를 만들 때 문서 품질의 벤치마크를 설정하는 것입니다. 이 튜토리얼에서는 Vale 린터를 사용할 것입니다.

린터와 함께 일종의 문서 자동화를 사용하는 것이 일반적입니다. 이 맥락에서 자동화라고 하면 CI/CD(지속적 통합 및 지속적 배포) 워크플로를 의미합니다. CI 는 문서 작성 및 테스트를 자동화합니다. CD는 코드 릴리스를 자동화합니다.

다양한 유형의 앱을 사용하여 CI/CD 워크플로를 구현할 수 있습니다. 이 자습서에서는 GitHub Actions를 사용하여 설명서 린터를 실행할 것입니다. GitHub Actions는 GitHub 리포지토리에서 직접 CI를 실행하므로 CircleCI 또는 Travis와 같은 타사 애플리케이션을 사용할 필요가 없습니다.

마지막으로, GitHub 작업은 이벤트 기반 입니다. 즉, 누군가가 pull 요청이나 문제를 작성할 때와 같이 어떤 일이 발생할 때 트리거됩니다. 이 예에서 GitHub 작업은 누군가가 변경 사항을 메인 브랜치로 푸시할 때 발생합니다.

GitHub 작업

먼저 GitHub 리포지토리를 만듭니다. 그런 다음 로컬에서 폴더를 만들고 이 폴더에 cd 를 넣습니다.

 mkdir automated-docs cd automated-docs

폴더에 들어가면 Git의 디렉터리를 초기화합니다.

 git init

리포지토리를 초기화했으면 계속해서 폴더에 대한 워크플로 디렉터리를 만듭니다.

 mkdir .github/ && cd .github/ && mkdir workflows/ && cd workflows/

워크플로는 모든 GitHub 작업을 저장하는 곳입니다. workflows 폴더를 만든 후에는 새 워크플로를 만듭니다. 이 워크플로의 이름을 vale.yml 로 지정하겠습니다.

 touch vale.yml

Vale.yml 은 YAML 파일입니다. 이 워크플로 파일에는 작업과 작업이 포함됩니다.

이제 즐겨 사용하는 텍스트 편집기에서 vale.yml 을 엽니다.

 nano vale.yml

다음을 복사하여 vale.yml 에 붙여넣고 컨텍스트와 구문을 살펴보겠습니다.

 # This is a basic workflow to help you get started with Actions name: CI # Controls when the workflow will run on: # Triggers the workflow on push or pull request events but only for the main branch push: branches: [ main ] pull_request: branches: [ main ] # Allows you to run this workflow manually from the Actions tab workflow_dispatch: # A workflow run is made up of one or more jobs that can run sequentially or in parallel jobs: # This workflow contains a single job called "build" build: # The type of runner that the job will run on runs-on: ubuntu-latest # Steps represent a sequence of tasks that will be executed as part of the job steps: # Checks-out your repository under $GITHUB_WORKSPACE, so your job can access it - uses: actions/checkout@v2 # Runs a single command using the runners shell - name: Run a one-line script run: echo Hello, world! # Runs a set of commands using the runners shell - name: Run a multi-line script run: | echo Add other actions to build, echo test, and deploy your project. env: GITHUB_TOKEN: ${{secrets.GITHUB_TOKEN}}

• name
  이것은 이름 또는 우리가 작업 흐름이라고 부르는 것입니다. 문자열입니다.
• on
  이것은 워크플로와 트리거를 제어합니다.
• jobs
  이것은 우리가 우리의 행동을 설정하고 통제하는 곳입니다. 작업이 실행될 환경을 선택합니다. 일반적으로 Ubuntu를 사용하는 것이 좋습니다. 그리고 여기에 우리의 행동을 추가할 것입니다.

GitHub에는 궁금한 경우를 대비하여 다른 모든 워크플로 구문 및 변수에 대한 가이드가 있습니다.

이 섹션에는 다음이 있습니다.

• GitHub 작업이 무엇인지 배웠습니다.
• 첫 번째 GitHub 워크플로를 만들었습니다.
• GitHub 워크플로 YAML 파일의 가장 중요한 부분을 식별했습니다.

다음으로 Vale를 사용하도록 GitHub 워크플로를 사용자 지정합니다.

GitHub 작업 파일에서 Vale 설정

기본 워크플로 파일을 복사했으면 이제 Vale 작업을 사용할 수 있도록 사용자 지정해야 합니다. 가장 먼저 할 일은 YAML 파일의 이름을 Docs-Linting 으로 변경하는 것입니다.

 # This is a basic workflow to help you get started with Actions. name: Docs-Linting

다음으로, 누군가 가 변경 사항을 GitHub의 메인 브랜치로 푸시 하면 Vale 테스트를 실행하려고 합니다. 누군가가 pull 요청을 생성할 때 테스트가 실행되는 것을 원하지 않으므로 YAML 파일의 해당 부분을 삭제할 것입니다.

 on: # Triggers the workflow on push or pull request events but only for the main branch push: branches: [ main ]

jobs 섹션은 워크플로 파일의 주요 부분이며 GitHub 작업 실행을 담당합니다.

 jobs: build: runs-on: ubuntu-latest steps: - name: Checkout uses: actions/checkout@master

이러한 작업은 최신 버전의 Ubuntu에서 실행됩니다. Checkout 작업은 GitHub 워크플로가 액세스할 수 있도록 리포지토리를 체크아웃합니다.

이제 GitHub 워크플로에 Vale 작업을 추가할 차례입니다.

 - name: Vale uses: errata-ai/[email protected] with: debug: true styles: | https://github.com/errata-ai/write-good/releases/latest/download/write-good.zip https://github.com/errata-ai/Microsoft/releases/latest/download/Microsoft.zip env: GITHUB_TOKEN: ${{secrets.GITHUB_TOKEN}}

우리는 우리의 행동을 Vale 라고 명명했습니다. uses 변수는 구현하려는 Vale 버전을 보여줍니다. 이상적으로는 가장 최신 버전을 사용해야 합니다. with 변수에서 debug 를 true 로 설정합니다.

styles 섹션은 Vale에 스타일 가이드를 추가할 수 있는 옵션을 제공합니다. 이 예에서는 write-good 및 Microsoft의 공식 스타일 가이드를 사용할 것입니다. 다른 스타일 가이드도 사용할 수 있습니다.

이 GitHub 작업의 마지막 부분은 env 입니다. 이 GitHub 작업을 실행하려면 비밀 토큰을 포함해야 합니다.

결과는 다음과 같아야 합니다.

 # This is a basic workflow to help you get started with Actions. name: Docs-Linting # Controls when the action will run. on: # Triggers the workflow on push or pull request events but only for the main branch push: branches: [ main ] # Allows you to run this workflow manually from the Actions tab workflow_dispatch: jobs: prose: runs-on: ubuntu-latest steps: - name: Checkout uses: actions/checkout@master - name: Vale uses: errata-ai/[email protected] with: debug: true styles: | https://github.com/errata-ai/write-good/releases/latest/download/write-good.zip https://github.com/errata-ai/Microsoft/releases/latest/download/Microsoft.zip env: GITHUB_TOKEN: ${{secrets.GITHUB_TOKEN}}

변경이 완료되면 파일을 저장하고 Git에 커밋하고 변경 사항을 GitHub에 푸시합니다.

 git add .github/workflows/vale.yml git commit -m "Added github repo to project" git push -u origin main

요약하자면 이 섹션에는 다음이 있습니다.

• 새 코드를 main 브랜치로 푸시할 때 발생하는 액션을 트리거했습니다.
• debug 를 true 로 설정하고 스타일 가이드를 식별하는 Vale 작업을 추가했습니다.
• GitHub 토큰을 추가했습니다.
• 변경 사항을 커밋하고 GitHub에 푸시했습니다.

다음 섹션에서는 Vale 구성 파일을 생성할 것입니다.

Vale 구성 파일 설정

프로젝트 디렉토리의 루트로 이동한 다음 touch .vale.ini . 텍스트 편집기에서 .vale.ini 를 엽니다. 다음을 복사하여 .vale.ini 에 붙여넣습니다.

 StylesPath = .github/styles MinAlertLevel = warning [formats] Markdown = markdown [*.md] BasedOnStyles = write-good, Microsoft

• StylesPath = .github/styles
StylesPath 는 Vale 스타일의 경로를 제공합니다.
• MinAlertLevel = warning
  최소 경고 수준은 경고의 심각도를 보여줍니다. 옵션은 suggestion , warning 및 error 입니다.
• [formats]
Markdown = markdown 은 형식을 Markdown으로 설정합니다.
• [*.md]
BasedOnStyles = write-good, Microsoft 는 .md 로 끝나는 모든 Markdown 파일에 대해 write-good 및 Microsoft 스타일 가이드를 실행합니다.

이 설정은 최소한의 것입니다. Vale 구성에 대해 자세히 알아보려면 설명서를 참조하십시오.

변경이 완료되면 파일을 저장하고 GitHub에 커밋하고 푸시합니다.

 git add .vale.ini git commit -m "Added Vale config file" git push -u origin main

이 부분에서는 Vale 구성 파일의 내부를 배웠습니다. 이제 샘플 문서를 작성할 차례입니다.

문서 생성 및 Vale GitHub 작업 트리거

이제 Vale 및 GitHub Actions가 작동하는 모습을 볼 시간입니다! Markdown 파일을 만들고 텍스트로 채울 것입니다. 그리고 DeLorean Ipsum으로부터 텍스트를 받을 것입니다.

프로젝트의 루트로 이동한 다음 touch getting-started.md . getting-started 파일을 생성했으면 DeLorean Ipsum으로 이동하여 문서용 더미 텍스트를 생성합니다. 그런 다음 텍스트 편집기로 돌아가 텍스트를 getting-started-md 에 붙여넣습니다.

 # Getting Started Guide I can't play. It's my dad. They're late. My experiment worked. They're all exactly twenty-five minutes slow. Marty, this may seem a little foreward, but I was wondering if you would ask me to the Enchantment Under The Sea Dance on Saturday. Well, they're your parents, you must know them. What are their common interests, what do they like to do together? Okay. Are you okay? Whoa, wait, Doc. What, well you mean like a date? I don't wanna see you in here again. No, Biff, you leave her alone. Jesus, George, it's a wonder I was ever born. Hey, hey, keep rolling, keep rolling there. No, no, no, no, this sucker's electrical. But I need a nuclear reaction to generate the one point twenty-one gigawatts of electricity that I need. I swiped it from the old lady's liquor cabinet. You know Marty, you look so familiar, do I know your mother?

파일을 저장하고 커밋한 다음 GitHub에 푸시합니다.

 git add getting-started.md git commit -m "first draft" git push -u origin main

변경 사항을 푸시한 후 저장소가 있는 GitHub로 이동합니다. Actions 탭으로 이동합니다.

왼쪽에 모든 워크플로가 표시됩니다. vale.yml 파일에 넣은 것과 같은 이름인 Docs-Linting 하나만 있습니다.

문서를 GitHub에 푸시하면 작업이 트리거됩니다.

작업이 문제 없이 실행되면 녹색 확인 표시가 나타납니다.

전체 보고서를 보려면 "추가된 문서"를 클릭하십시오.

11개의 경고를 받은 것을 볼 수 있습니다. "족제비 단어" 경고를 처리합시다. 텍스트 편집기로 getting-started.md 를 열고 "exactly"라는 단어를 삭제합니다.

 # Getting Started Guide I can't play. It's my dad. They're late. My experiment worked. They're all twenty-five minutes slow. Marty, this may seem a little foreward, but I was wondering if you would ask me to the Enchantment Under The Sea Dance on Saturday. Well, they're your parents, you must know them. What are their common interests, what do they like to do together? Okay. Are you okay? Whoa, wait, Doc. What, well you mean like a date? I don't wanna see you in here again. No, Biff, you leave her alone. Jesus, George, it's a wonder I was ever born. Hey, hey, keep rolling, keep rolling there. No, no, no, no, this sucker's electrical. But I need a nuclear reaction to generate the one point twenty-one gigawatts of electricity that I need. I swiped it from the old lady's liquor cabinet. You know Marty, you look so familiar, do I know your mother?

변경 사항을 저장하고 Git에 커밋하고 파일의 새 버전을 GitHub에 푸시합니다. GitHub 작업을 트리거 해야 합니다.

"Deleted weasel word"를 클릭하면 현재 10개의 경고만 표시되고 "weasel word" 경고가 사라집니다. 만세!

우리는 끝났고 많은 부분을 다루었습니다. 이 섹션에는 다음이 있습니다.

• Vale GitHub Actions 저장소에 문서를 추가했습니다.
• Vale GitHub 작업을 트리거했습니다.
• Vale에서 생성한 오류를 수정하고 변경 사항을 GitHub로 다시 푸시했습니다.

결론

점점 멀어지는 세상에서 좋은 문서 와 좋은 문서 워크플로의 우선 순위를 지정하는 것이 중요합니다. 먼저 스타일 가이드를 만들어 "좋은 것"이 무엇인지 정의해야 합니다. 문서의 규칙을 파악했다면 이제 자동화할 차례입니다.

문서는 코드 기반처럼 다루어야 합니다. 지속적으로 반복되고 마지막으로 업데이트했을 때보다 조금 더 나아지고 있는 살아있는 작업의 본체입니다.