開発者向けのドキュメントワークフローを自動化する方法

このチュートリアルを最大限に活用するには、Git、GitHub、Linux、およびコマンドラインに精通している必要があります。

なぜ高品質のドキュメントを気にする必要があるのですか？

多くのチームがドキュメントの作成に苦労しています。 フレームワークを確認しようとすると、ドキュメントが古くなったり、不明瞭になったりすることがよくあります。 これは、チームメンバーが機能を追加しようとしたときに内部のフラストレーションにつながる可能性がありますが、ドキュメントが不十分なため、現在の機能がどのように機能するかを理解していません。 これは、仕事の非生産的な時間につながる可能性があります。

不十分なドキュメントはまた、優れた顧客体験を損ないます。 Ask YourDeveloperの著者でTwilioの創設者であるJeffLawsonによると、APIを製品として販売している場合、ドキュメントは技術的な利害関係者にとって究極の広告です。 IBMは文書化の重要性について調査を行い、回答者の90％が、製品の文書化の品質に基づいて購入を決定したことを認めました。

優れたドキュメントを作成することは、開発者と顧客のエクスペリエンスにとって重要です。

ドキュメントが非常に重要な場合、エンジニアリングチームがドキュメントの優先順位を下げるのはなぜですか？

ドキュメントを作成すると、開発者は「フロー」から抜け出すことができます。 ドキュメントはメインコードベースの外にあることが多く、検索して更新するのは面倒です。 それをExcelスプレッドシートまたは独自のCMSに入れることは珍しいことではありません。

ドキュメントを自動化し、ドキュメントワークフローを改善すると、これが修正されます。

高レベルからのドキュメントの自動化

ドキュメントの自動化とはどういう意味ですか？ これは、一般的なソフトウェア開発手法を採用することを意味します。 ドキュメントを自動化すると、次のようになります。

• Markdownでドキュメントを書く。
• 継続的インテグレーションと継続的デプロイ（CI / CD）パイプラインを使用して、エラーの修正や更新のデプロイなどのタスクを実行します（このチュートリアルでは、GitHubアクションに焦点を当てます）。
• Valeのようなツールを実装して、スタイルガイドを適用し、一般的な文法上の誤りを修正します。

スタイルガイド

ValeやGitHubActionsなどのツールを使用してスタイルガイドを自動化する前に、スタイルガイドとは何かを正確に定義してみましょう。

ドキュメントを書いているときの気持ちが少しずれているように見えることをご存知ですか？ あなたの説明は他のドキュメントに適合しませんが、なぜそれらが間違っているのかを完全に説明することはできません。 文章はその概念を説明していますが、それは合わないようです。

この感覚を感じると、声やトーンがずれている可能性があります。 QA、エンジニアリング、および製品チームによって編集されたドキュメントを開発している場合でも、声とトーンを洗練することは、文章をまとまりのあるものにする方法です。 以下は、TorreyPodmajersky著の『 Strategic Writing for UX 』から抜粋した、市内バスアプリケーションTAPPのスタイルガイドの例です。

TAPPはトランジットアプリケーションです（バスと電車用）。 表のヘッダーは、企業としてのTAPPの価値を示しており、効率的で、信頼でき、アクセスしやすいものです。 表の左側には、スタイルガイドでカバーされているさまざまな部分（概念、語彙、冗長性、文法、句読点）がリストされています。

一緒に、これらはスタイルガイドを作ります。 ヘッダーは値を紹介し、表の左側には、語彙、文法、句読点など、書かれた資料に見られるさまざまなコンポーネントが表示されます。 このスタイルガイドの優れている点は、エンジニアとコピーライターが、Tappのブランドアイデンティティを促進するために使用する大文字と句読点を明確に理解できることです。

テクニカルライティングスタイルガイド

すべてのスタイルガイドがテーブルに入っているわけではありません。 Microsoftには、頭字語からバイアスのないコミュニケーション、チャットボットまで、すべてを網羅する包括的なガイドとして機能するWebサイト全体があります。 もちろん、スタイルガイドを持っているのはマイクロソフトだけではありません。 Googleにも1つあります。

スタイルガイドのトラブル

スタイルガイドは、ドキュメントに真剣に取り組む企業にとって素晴らしい出発点です。 彼らは、開発者が押し出している主要な機能について正確に書く方法について持っているかもしれない多くの混乱を解決します。

スタイルガイドの問題は、スタイルガイドが書き込みプロセスに摩擦を加えることです。 私を含む多くの作家は、質問があるたびに書くのをやめたり、スタイルガイドを見たりすることを気にしません。 場合によっては、スタイルガイドが煩雑で参照が難しいことがあります。たとえば、Microsoftスタイルガイドの長さは1,000ページを超えています。

ドキュメント用のリンターとCI/CD

あなたがプログラマーなら、おそらくリンターに精通しているでしょう。 リンターは、チームにコーディング標準を適用するための理想的な方法です。 ドキュメントについても同じことが言えます。 リンターを作成すると、ドキュメントの品質のベンチマークが設定されます。 このチュートリアルでは、Valeリンターを使用します。

リンターと一緒にある種のドキュメント自動化を使用するのが一般的です。 このコンテキストで自動化とは、継続的インテグレーションと継続的展開（CI / CD）ワークフローを指します。 CIは、ドキュメントの構築とテストを自動化します。 CDはコードのリリースを自動化します。

さまざまな種類のアプリを使用して、CI/CDワークフローを実装できます。 このチュートリアルでは、GitHubアクションを使用してドキュメントリンターを実行します。 GitHubアクションはGitHubリポジトリで直接CIを実行するため、CircleCIやTravisなどのサードパーティアプリケーションを使用する必要はありません。

最後に、GitHubアクションはイベント駆動型です。つまり、誰かがプルリクエストや問題を書き込んだときなど、何かが発生したときにトリガーされます。 この例では、誰かが変更をメインブランチにプッシュすると、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テストを実行します。 誰かがプルリクエストを作成したときにテストを実行したくないので、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という名前を付けました。 used変数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ブランチにプッシュしたときにアクションが発生するようにトリガーしました。
• Valeアクションを追加し、 debugをtrueに設定し、スタイルガイドを識別しました。
• 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構成ファイルの内部について学習しました。 次に、サンプルドキュメントを作成します。

ドキュメントの作成とValeGitHubアクションのトリガー

次に、ValeとGitHubActionsの動作を確認します。 Markdownファイルを作成し、テキストで埋めます。 そして、DeLoreanIpsumからテキストを取得します。

プロジェクトのルートに移動し、 touch getting-started.mdします。 入門ファイルを作成したら、DeLorean getting-startedに移動して、ドキュメント用のダミーテキストを作成します。 次に、テキストエディタに戻り、テキストを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 ]タブに移動します。

左側にすべてのワークフローが表示されます。 Docs-Lintingという名前の名前が1つだけあります。これは、 vale.ymlファイルに入力したのと同じ名前です。

ドキュメントをGitHubにプッシュすると、アクションがトリガーされます。

アクションが問題なく実行された場合は、緑色のチェックマークが表示されます。

完全なレポートを取得するには、「追加されたドキュメント」をクリックしてください。

11個の警告が表示されます。 「逃げ文句」の警告に対処しましょう。 テキストエディタに戻り、 getting-started.mdを開いて、「正確に」という単語を削除します。

 # 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アクションをトリガーする必要があります。

「逃げ文句を削除しました」をクリックすると、警告が10個しかなく、「逃げ文句」の警告が消えていることがわかります。 やったー！

私たちは終わりました、そして私たちは多くの地面をカバーしました。 このセクションには、次のものがあります。

• ValeGitHubActionsリポジトリにドキュメントを追加しました。
• ValeGitHubアクションをトリガーしました。
• Valeによって生成されたエラーを修正し、変更をGitHubにプッシュバックしました。

結論

ますます遠隔化する世界では、優れたドキュメントと優れたドキュメントワークフローを優先することが重要です。 まず、スタイルガイドを作成して「良い」とは何かを定義する必要があります。 ドキュメントのルールを理解したら、自動化する時が来ました。

ドキュメントは、コードベースのように扱う必要があります。つまり、常に繰り返され、最後に更新したときよりも少し良くなっている一連の作業です。