RAKSUL TechBlog

ラクスルグループのエンジニアが技術トピックを発信するブログです

マイクロサービスドキュメントガイドラインを策定した話

RAKSUL Advent Calendar 2021 1日目です!なんとトップバッターです!

こんにちは!今年8月に発足したラクスル事業本部 HoE(※)室 の市島です!

※ HoE:Head of Engineering

記念すべき RAKSUL初のAdvent Calendar 1日目、今回はラクスル事業部にてマイクロサービスを開発する際、そのサービスを組み込む(利用する)開発者に向けて書くべきドキュメントのガイドラインを策定した話について述べます。

はじめに

ラクスルでは日本国内だけでなく、インド・ベトナムでのグローバル採用も行なっており、ラクスル事業部ではエンジニアだけであれば、およそ40%の人が日本以外の国籍です。(2021/12/1時点)

今後も積極的に採用していく予定であり、このペースであれば2年後には50%に届く勢いです。

ラクスルにはチラシやポスターなどの印刷商品を扱うraksul.comだけでなく、マスクやお菓子といったノベルティを扱うnovelty.raksul.com、ダイレクトメールを扱うdm.raksul.comといったサブドメインを持つECサイトがあります。

各ECサイトは独立して開発をしていますが、内部にはこれらの複数サービスを横断した決済基盤システムや入稿されたデータのチェックを行うデータチェック基盤システムといった基盤系システムが存在します。

ここでは一旦上記のような基盤系システムをマイクロサービスと呼称します。

やったこと

しかしながら、こういった基盤系システムを組み込むにあたって必要なドキュメントが散らばりがち、かつ日本語であるため、日本語ネイティブではないメンバーとしては組み込みがしにくく、基盤系システムの開発をするメンバーはその問い合わせへの対応工数が増加しているという問題がありました。

そこでHoE室では、マイクロサービスドキュメンテーションガイドラインを策定し、基盤系システムのユーザに向けたドキュメントの作成指針を設けることで、この問題を解決しようと試みました。

Principle

今回策定したガイドラインには以下のPrincipleを定めました。

  • EASY INTEGRATION
    • 組み込みたいエンジニアがドキュメントを読めば組み込める状態であるべき
  • REACHABLE
    • repositoryのREADMEがドキュメントルートであり、そこから開発に必要なドキュメント全てにアクセスすることが可能であるべき
  • OWNERSHIP
    • 良いドキュメントを書くことまでがマイクロサービス運営者の責務である

具体的な内容

上記のPrincipleを具体に落とし込んだ内容が以下になります。

ユーザファーストであること

READMEの構成はユーザガイドが先頭にあるべきだと規定しています。その理由としては基盤系システムの開発者より基盤を利用する開発者の方が多いこと、また基盤系システムから見て、その基盤系システムを組み込む側の開発者はユーザであるという視点を持ってほしいという意図があります。

開発に必要なドキュメントはGitHubのrepositoryのREADMEから辿れるようになっていること

READMEさえ見れば、組み込みに必要な情報は全て揃うようになっているべきと規定しています。

ラクスル事業部ではREADMEと定めていますが、ここは決めの問題で、定めた場所に必要な情報がしっかりと集約されている状態になっていることが重要だと考えています。

コンテンツについて

ユーザガイドには以下のコンテンツを書くべきと定めています。

  • TOC(Table of contents)
  • What is this?
  • Getting started
    • アクセストークンの生成方法やクライアントの利用方法といった組み込みに必要なプロセスを書く
  • Concepts(optional)
    • ハイコンテクストなドキュメントを避け、エンジニアがサービスを理解するためにそのサービス内の重要なコンセプトを説明する
    • 例えばデータチェック基盤では「Operator Commission」という概念が出てくるのですが、これはオペレーターの目でデータをチェックするというデータチェック方法の1つである、といった旨の説明がされています
  • API reference
  • Example (optional)
  • Owner
    • オーナーが誰かを連絡先(slack channelやgroup mention)と共に書く
    • 誰がこのドキュメントを管理しているかを明確にし、何を書くべきかを把握してもらうことで、各マイクロサービス運営者にOWNERSHIPを意識してもらおうという意図があります

翻訳ポリシー

少し毛色が違うのですが、日本語と英語を併記する場合の翻訳ポリシーについても記載しています。基本的には英語のみで書きましょう、というのと「日本語も併記する場合はこうしてね」といった書き方を定めています。

おわりに

HoE室では前述の原則を定め、これが絵に描いた餅にならないようにするべく、重要なドキュメントを英訳し、また社内での具体的なお手本とするためにいくつかのrepositoryのREADMEをガイドラインに沿ってUpdateしました。

ラクスル事業部では、まずマイクロサービスのドキュメントというスコープに限定してガイドラインを策定することで小さく始めています。今後はこのスコープを広げていき、最終的にはマイクロサービスに限らない「ドキュメントガイドライン」を定めて、しっかりと運用させ続けることができればゴールなのではないかと考えています。

ラクスルではエンジニアを募集中しています! https://recruit.raksul.com/career/engineer/

ラクスルのアドベントカレンダー全編はこちらから