Aivenの開発者向けドキュメントへの貢献

<font color="Grey">*[Contributing to Aiven's developer documentation](https://aiven.io/blog/contribute-to-aiven-docs)の翻訳です。*</font>

2022年6月16日

# Aivenの開発者向けドキュメントへの貢献

Aivenはオープンソースプロジェクトとして開発者向けドキュメントを作成しています！docs-as-codeをどのように活用しているか、ぜひご覧ください。

## ドキュメンテーションへの貢献Aiven開発者


Aivenでは、ドキュメンテーションは部門横断的な取り組みです。同僚として、より経験豊富なドキュメンテーション貢献者は、新人をオンボーディングし、彼らが[developer.aiven.io](https://developer.aiven.io)に最初の編集を行う際に手を貸すためのセッションを運営しています。


今日、私たちは外部からの貢献を歓迎できるところまで来ています。もしあなたが私たちのドキュメントを使っていて、何かが欠けていると感じたり、それを改善する機会を見つけたりしたなら、私たちの開発者向けドキュメントの成長に貢献することを検討してください。


### コードとしてのドキュメントについて


[Write The Docs](https://www.writethedocs.org/guide/docs-as-code/)によると、「コードとしてのドキュメント(Docs as Code)」とは、コードと同じツールを使ってドキュメントを書くべきだという哲学のことです。つまり、課題追跡システム、バージョン管理、MarkdownやreStructuredTextのようなプレーンテキストのマークアップ、コードレビューの実装、ドキュメントの自動テストを使うことです。


また、Docs as Codeは、ソフトウェア開発チームが行うのと同じワークフローに従い、製品チームと密接な関係を持つことも意味します。これにより、ライターと開発者の両方がドキュメントのオーナーシップを感じ、可能な限り良いものを作るために協力し合うという文化が可能になります。


### 私たちが選んだテクノロジー


[Developer.aiven.io](https://developer.aiven.io)は、Aivenの他のほとんどのものと同様にオープンソースです。プラットフォームはオープンソースツールを使用し、コンテンツ自体は[クリエイティブ・コモンズ](https://creativecommons.org/)ライセンスを取得しています。私たちは確立されたワークフローとレビュープロセスを使用し、GitHubをコラボレーションに使用しています（すべての変更の完全な監査履歴があります）。GitHubのアクションは、進行中の各プル・リクエストのプレビューのデプロイを含む、自動テストとデプロイの実行を引き受けます。


技術スタックは、[Sphinx](https://www.sphinx-doc.org/)といくつかの優れた拡張機能、散文のリンティングのための[Vale](https://vale.sh/)、ダイアグラムのための[MermaidJS](https://mermaid-js.github.io/mermaid/#/)で構成されています。私たちは、あなたのドキュメントが常にとてもとても速く読み込まれるように、このすべてを静的なサイトにパッケージしています。


### プロジェクトへの貢献


ここでは、[プロジェクト](https://github.com/aiven/devportal)を少し紹介します：


* docs/`フォルダにはすべての記事が入っている。
	+ docs/`フォルダにはすべての記事が入っている。
* CONTRIBUTING`ファイルには記事のテンプレートとスタイルガイドがあります。
	+ reStructuredTextのいくつかのヒントは `README` にもあります。
* REVIEWING`ファイルには査読者のためのガイドラインがあります。


新しいことに取りかかる前に、[issue list](https://github.com/aiven/devportal/issues)をチェックし、issueを自分に割り当てるか、すでにissueがあればコメントしてください。


#### お気に入りのIDEを使う


あなたのマシンには、すでに開発者用の環境があることでしょう。ターミナルかコマンドプロンプトを使って [リポジトリ](https://github.com/aiven/devportal) をクローンし、新しいブランチを作成して変更を加え、プルリクエストをオープンします。


README`ファイルの指示に従って必要な依存関係をインストールし、変更を必ずローカルでビルドしてテストしてください。


Visual Studio Codeを使う？私の同僚であるLorna Mitchellが、彼女のブログで[VSCodeのセットアップ](https://lornajane.medium.com/vscode-setup-for-technical-writers-83867870ed73)をシェアしてくれました。


#### GitHubデスクトップを使う


GUI (Graphical User Interface) ツールを探しているなら、GitHub Desktop がおすすめです。完全なオープンソースで、私たちも気に入っています！


[GitHub Desktop](https://desktop.github.com/)をダウンロードし、GitHubアカウントでログインしましょう。それから [リポジトリ](https://github.com/aiven/devportal) をクローンするか、すでにクローンしている場合は `ファイル > ローカルリポジトリを追加` を選択してローカルパスを指定します。新しいブランチを作成し、好きなエディターを使って変更を加え、コミットします。


![docs-as-code github デスクトップを使用してローカルリポジトリを追加する](https://cdn.sanity.io/images/sczeoy4w/production/7dd0389c7cfe0e838f077bb4d4107a818a825825-1429x982.png?q=80&fit=min&auto=format&dpr=1.5)


#### GitHub コードスペースを使う


このプロジェクトでCodespacesが使えるようになりました。Codespacesを使うには、リポジトリの緑色の「<> Code」ボタンを選択します。


![docs-as-code select the codespaces button](https://cdn.sanity.io/images/sczeoy4w/production/045313f6dd77a8f64cc02aba374de017972511a1-1812x1255.png?q=80&fit=min&auto=format&dpr=1.5)


コードスペースは、メインブランチで作成することも、フィーチャーブランチや PR で共同作業することもできます。


![docs-as-codeはフィーチャーブランチで共同作業する](https://cdn.sanity.io/images/sczeoy4w/production/fd48e9912ba4d262931f74cb5fbabadc03f20089-1812x1227.png?q=80&fit=min&auto=format&dpr=1.5)


同僚からのプルリクエストを選び、彼らが行った変更をチェックし、サイトを構築する。


![docs-as-code check out pull request](https://cdn.sanity.io/images/sczeoy4w/production/d24916db4f0cf7de38f19f2815526b2ec59e7712-1811x826.png?q=80&fit=min&auto=format&dpr=1.5)


しかも速い！


### 参加する


私たちは自分たちのドキュメンテーション・プロジェクトに誇りを持っていますが、だからといって私たちが積極的に取り組んでいないわけではありませんし（公開されているので、私たちが取り組んでいることがわかります！）、改善できないわけでもありません。もし、もっと良くなると思われる点を見つけたら、issueを発行して私たちに知らせてください。さらに良いのは、自分自身で改善することです。私たちの誰かがあなたと一緒にその変更を検討し、あっという間に掲載され、感謝と自画自賛の両方の権利を得ることができます。


便利なリンクを簡単にご紹介します：


* 私たちのドキュメント<https://docs.aiven.io>
* GitHubプロジェクト<https://github.com/aiven/devportal>
* [GitHubアクションを使ったプルリクエストの自動化](https://aiven.io/blog/how-to-automagically-open-pull-requests-with-github-actions)
* Aiven ってなんだろうと思っている方、ドキュメントを書くためにいろいろ試してみたい方は、[無料トライアルに申し込む](https://console.aiven.io/signup)


--


ご意見やご質問は、[Twitter](https://twitter.com/aiven_io)または[LinkedIn](https://www.linkedin.com/company/aiven/)までお寄せください。[変更履歴](https://aiven.io/changelog)と[ブログ](https://aiven.io/blog)のRSSフィードをフォローしてください。また、Aivenと私たちのサービスに関する最新ニュース、さらにオープンソース全般に関する情報をご希望の方は、[月刊ニュースレターを購読](https://aiven.io/newsletter)してください！