Blog Handbook

GitLab Blog ハンドブックへようこそ! GitLab Blog は Content Marketing チームによって管理されています。ブログのマネージングエディターは Sandra Gittlen（@sgittlen）です。

ブログ投稿とは何か?

GitLab では、ブログ投稿は主に、オーディエンス（DevSecOps プロフェッショナル）に役立つ情報を共有することに焦点を当てています。ブログ投稿を提案または執筆する際は、それが読者に何を提供するかを常に考えてください。投稿がより内部向け、あるいは一種の個人的なエッセイである場合、ブログには合わない可能性が高いです（ただし、あなた個人の LinkedIn ページには載せられるかもしれません）。

ブログは以下のカテゴリーに分類されます。

• 技術的チュートリアル/ハウツー
• 視点/ソートリーダーシップ
• 機能とケイパビリティの紹介
• オープンソースコミュニティ
• 顧客事例/インタビュー
• 会社のアナウンス（Executive comms チームとのパートナーシップで実施）
• 機能/変更などのアナウンス
• パートナーシップ/アライアンスを紹介するゲストブログ

誰が GitLab Blog にコンテンツを公開できるか?

GitLab では誰もが貢献できます。ブログにとって、これは皆さんのブログの提案、アイデア、ドラフトを歓迎することを意味します。ただし、メインブログは GitLab の多くの公式の声の 1 つであり、つまりそこに公開されるコンテンツは、私たちが GitLab（会社と製品の両方）を正確に表現していることを確実にするために、慎重に精査されなければなりません。Blog Managing Editor および Director of Global Content Marketing が 公式 GitLab ブログの directly responsible individuals（DRI）であり、この責任を担っています。

GitLab Blog についてご質問がある場合は、[email protected] までご連絡ください。

ブログのアイデアを提案する方法 - 新プロセス

ブログのアイデアを提案するには、blog submission template を使って Issue を作成してください。

アイデアを提出する際は:

• テンプレートのすべての質問に答えてください。それらは、私たちがあなたのアイデアに対してフィードバックを提供するのに役立ちます。
• 目標とする公開日の少なくとも 2 週間前にアイデアを提出してください。
• コーポレート/comms のリクエスト、または短納期のブログについては、Issue を提出した上で @sgittlen に直接連絡してください。

注: blog submission template を通じて、Blog チームにタイポを通知したり、変更をリクエストしたりすることもできます。

ブログエディターはあなたのピッチをレビューし、a) 投稿を承認する、b) 改善の提案をする、または c) なぜそのアイデアがブログに合わないかもしれないかを説明し、メッセージを発信する他のアイデアを提供する、のいずれかを行います。

ニュースレターコンテンツのリクエストについて: この Issue にリクエストを追加してください。

外部からの貢献

注: GitLab は、依頼していないブログの投稿を受け付けません。GitLab パートナーで、検討のためにブログ投稿のアイデアをピッチしたい場合は、[email protected] にメールしてください。GitLab コミュニティメンバーで、検討のためにブログ投稿のアイデアをピッチしたい場合は、[email protected] にメールしてください。ピッチとともにブログのドラフトは送らないでください。

ピッチのアイデアは、GitLab Blog と私たちの読者に関連していなければならず、以下の情報を含む必要があります。

• あなたのブログは何についてのものですか? できるだけ具体的にしてください。

• 以下のうち、あなたのブログを最もよく表すのはどれですか?（少なくとも 1 つのボックスをチェックしてください。）

• 機能/ケイパビリティを最大限に活用する方法に関するチュートリアル/ハウツー

• GitLab プラットフォームの使い方に関するベストプラクティス

• オープンソースコミュニティと GitLab

• パートナー/アライアンスのインテグレーション

• その他 - 説明してください

すべてのブログのピッチアイデアと提出物は、GitLab チームメンバーによって精査・レビューされます。

ブログエディターの皆さん、貢献された記事の冒頭に次の 2 文を追加してください。

エディター注: 私たちは時折、コミュニティのメンバーを GitLab Blog への貢献に招待しています。私たちと共創してくれた [entity name] に感謝します。

外部からの貢献は、External Blog Submissions Terms の対象となります。GitLab に資料を提出する前に、このドキュメントを読み、条件に同意してください。

アイデアが承認された後にブログのドラフトを提出する方法

ブログのピッチが承認されたら、 執筆者は以下のいずれかのオプションを使ってドラフトを提出します。

• GitLab でマージリクエストを通じて提出する。これを行うには、リポジトリからこの手順に従ってください、または IDE 向けはこちら。注意深く従ってください! ご質問があれば @sgittlen に連絡してください。

• 私たちの基本的なコンテンツ管理システムである Decap を通じて、これらの手順を使って提出する。注意深く従ってください! ご質問があれば @sgittlen に連絡してください。

• Blog Submission template（Google ドキュメント）を使って Google Docs 経由で提出し、ブログを執筆し、Google ドキュメントが Issue にリンクされていることを確認する。Blog チームが提出物を受け付けるには、テンプレートのすべてのフィールドを記入する必要があります。 執筆者は Issue で @sgittlen をタグ付けし、ドキュメントのリンクをコメントに記載し、編集の準備が整ったら（必要なすべての承認とレビューが完了した後に）Google ドキュメントを共有します。注: すべての画像は Google ドキュメント内にインラインで含める必要があります。

注: すべてのブログ提出物には現在、call to action（CTA）が必要であり、ブログのドラフトテンプレートで CTA の提供を求められます。CTA とは、読者があなたのブログを読んだ後に次に取ってほしい行動のことです。別のページに移動して詳しく知ってほしいですか、トライアルに登録してほしいですか、ウェビナーに登録してほしいですか、デモを見てほしいですか、など? 私たちは、ブログの全体的なメトリクスの一部として CTA を追跡できます。

どの方法でブログを提出するにせよ、必ず @sgittlen をタグ付けしてください。

ブログは、Blog チームのレビュー/承認なしには公開できません。

MR のフロントマターガイド

MR には以下のフロントマターが含まれます。各セクションの後のコメントを参照してください

seo:
  title: the blog post title
  description: the blog post description
  <!-- Blog team will fill this area in -->
config:
  slug: blog-post-slug
  featured: false
  template: BlogPost
  <!-- blog team will fill this in -->
content:
  title: the blog post title
  <!-- ideal length - 55-60 characters -->
  description: the blog post description
  <!-- ideal length - no more than 155 characters -->
  authors:
    - Blog post author
  <!-- Format: Sandra Gittlen (if this is your first time contributing, leave blank, and if there are multiple authors, add a comma no space between)-->
  heroImage: images/blog/hero-images/logoforblogpost.jpg
  <!-- blog team will fill this in -->
  date: '2021-03-31'
  category: engineering
  <!-- blog team will fill this in -->
  tags:
    - community
  <!-- blog team will fill this in -->
  body: |
    add the blog post body text in markdown

ブログの編集プロセス

Blog チームは、Issue と Google ドキュメントを使って、執筆者に最初の編集/質問を伝えます。その後、Blog チームはブログを CMS に入れ、必要に応じてプレビューリンクを執筆者/DRI と共有します。注: ブログは Contentful から公開されます。

公開後に変更が必要な場合、執筆者は Slack 経由で Blog チームに連絡して変更を説明するか、公開ページの一番下に移動して「edit this page」をクリックして MR を提出します。これにより MR が開始されます。

Blog チームは、公開されるとブログの URL を執筆者と共有します。

ブログ投稿の公開は、編集カレンダーに従って行われます。ただし、緊急のブログに基づいて変更される場合があります。Blog チームは、想定される公開日について執筆者を最新の状態に保ちます。

法務レビュープロセス

一部のブログ投稿は、私たちの Materials Legal Review Process/SAFE プログラム に従って、法務によるレビューを受ける必要があります。執筆者は、Google ドキュメントを Blog チームと共有する前に、SAFE ガイドラインを確認し、Legal の承認を得る責任があります。このプロセスには時間がかかる場合があるため、それに応じて目標公開日を計画してください。

GitLab には bias for action がありますが、Blog チームも同様です。ただし、GitLab Blog は公開されるアセットであり、会社を代表しています。Blog チームがブログ投稿に含まれる情報について懸念や疑問を抱いた場合、Blog チームは、会社にとっての潜在的なリスクを軽減するために、Legal、Corporate Communications、Partner Marketing、CMO などがブログ投稿をレビューできるまで、ブログ投稿を保留する権限を持っています。

SAFE ガイドラインについてハンドブックページを読んで、Materials Legal Review Process に従うことで、詳しく学んでください。

公開済みブログへの変更を提案する方法

• GitLab の内部の方で、公開済みの GitLab ブログへの変更を提案したい場合は、必要な変更を URL とともに詳細に #content Slack チャンネルに投稿して @sgittlen をタグ付けするか、Slack で @sgittlen に直接 ping するか、または公開ページの一番下に移動して「Edit this page」をクリックして必要な変更を含む MR を作成してください。これにより MR が開始されます。

• GitLab の外部の方は、提案する変更の詳細を添えて Sandra Gittlen（[email protected]）にメールするか、または公開ページの一番下に移動して「Edit this page」をクリックして必要な変更を含む MR を作成してください。これにより MR が開始されます。

Blog チームとのコミュニケーション

チャットチャンネル:

• 質問には #content を使う（@sgittlen もタグ付けする）
• 最近公開された記事に関する更新を見るには #content-updates を使う
• Slack で @sgittlen に直接連絡する

その他の関連ページ

• Editorial style guide
• Brand guidelines
• Monthly release post

ブログを起草する際の考慮事項

ブログ執筆者向けの Diversity, Inclusion, and Belonging（DIB）チェックリスト

私たちのブログコンテンツが、diversity、inclusion、belonging という私たちの会社の価値観を表現していることが重要です。これらの点のすべてがあなたのブログ投稿に関連するわけではありませんが、執筆プロセス全体を通じて意識すべき重要な価値観とプラクティスです。ブログ編集チームはこれらを確認しようとしますが、すべてのコンテンツがこれらの価値観とプラクティスを念頭に置いて作成される方が良いです。ご質問があれば、私たちや DIB チームのメンバーをタグ付けしてください!

インクルーシブなライティング

• 短く簡潔な文を書きましょう。短い文による明確なライティングは、読者がついていきやすくなります。
• 専門用語の使用を制限し、専門用語的な言葉を使わなければならない場合は、最初の出現時に定義しましょう。
• GitLab はグローバルコミュニティを持つグローバルチームなので、グローバルなオーディエンスに向けて書くようにしましょう。これは、地域的なメタファーの使用を制限し、米国中心の方法で書かないことを意味します。
• 投稿は インクルーシブな言葉遣いを使っていますか?
• ブログ投稿内のすべての個人は、その 希望する代名詞を使って引用されていますか? ヒント: 誰かの希望する代名詞が分からない場合は、本人に尋ねるだけです。その人は team page profile と Slack プロフィールにも含まれているはずです。

その他の DIB ライティングのヒント

• あなたのブログ投稿はバイアスがかかっていますか? 私たちには皆、無意識のバイアスがあります。DIB ハンドブックページの無意識のバイアスのリストを確認し、自分のバイアスを認識し管理するための戦略を実践しましょう。
• まだ質問がある場合は、ためらわずに編集チームリードの @sgittlen、ブログ Issue 内の該当する team member resource group（TMRG）のリードをタグ付けするか、質問を添えて [email protected] にメールしてください。

ブログのカテゴリーとタグ

カテゴリー

投稿ごとに以下のカテゴリーの 1 つだけ を使用してください。 大文字小文字、スペル、その他何も 変更しないでください。 そうしないと別のカテゴリーが作成されてしまい、これは誤って行いたくないことです。

投稿がどのカテゴリーに属するか分からない場合は、MR にプレースホルダーを入れ、その旨をレビュアーへのコメントに残してください。

• agile planning - Agile planning に関する投稿
• ai-ml – プラットフォーム内または業界全体での AI/ML に直接焦点を当てる投稿
• customer stories - 顧客が GitLab DevSecOps プラットフォームをどう使っているかに関する投稿
• bulletin board - より短いブログ/アナウンスを入れる場所
• DevSecOps - DevSecOps について一般的に扱う投稿
• engineering – 技術的で実用的なコンテンツ。何かのやり方、何かの使い方、または問題の解決方法を扱うものはすべてこのカテゴリーに入るべきです
• open source – 私たちのコミュニティ、ユーザー、またはより広いオープンソースコミュニティからの、またはそれらに関するストーリー
• product - 機能、ロードマップ、戦略に関する詳細
• news – 会社または製品のアナウンス（ポリシー変更、運用上のアナウンス、破壊的変更を含む）、ニュース、またはイベント
• security – セキュリティ関連の投稿
• releases - リリース投稿、セキュリティおよびパッチリリース。releases カテゴリーの投稿は、sites/uncategorized/source/blog/blog-posts ではなく sites/uncategorized/source/releases/posts ディレクトリに入れる必要があります。詳細は Release Post handbook を参照してください。

タグ

これらは、読者が特定の主題に関心がある場合に、類似の投稿を見つけるのに役立つように含まれています。タグは各ブログ投稿の上部に表示され、タグをクリックすると、指定されたタグを持つすべての投稿を表示できる特定の /blog/tags/specific-tag に移動します。

好きなだけタグを含められ、カンマで区切ります。以下のリストのタグのみを含め、大文字小文字が区別されることに注意してください。

• agile
• AI/ML
• automotive
• AWS
• bug bounty
• careers
• CI/CD
• cloud native
• code review
• collaboration
• community
• contributors
• customers
• demo
• design
• developer survey
• DevSecOps
• DevSecOps platform
• embedded development
• education (articles about the education sector)
• events
• features
• financial services
• frontend
• git
• GitOps
• GKE
• google
• growth
• inside GitLab
• integrations
• kubernetes
• news
• open source
• partners
• patch releases
• performance
• product
• production
• public sector
• releases
• remote work
• research
• security
• security releases
• security research
• solutions architecture
• startups
• testing
• tutorial
• UI
• user stories
• UX
• webcast
• workflow
• zero trust

メディアの埋め込み

ビデオを含める手順。

コードブロックの追加

コードブロックを追加する手順。

Mermaid チャート

mermaid チャートを MR に埋め込む方法。チャートが正しくレンダリングされない原因となるニュアンスがあるので、ぜひ読んでください。

画像の準備

• オリジナルのカバー画像を作成する場合、すべてのディスプレイで最適な品質を得るために、寸法は 1800px x 945px にすべきです。
• すべての画像は 1MB 未満を目指すべきです。JPEG は PNG より小さくなる傾向があるので、可能な場合は JPEG を使ってください。
• Preview でサイズ変更するには、Tools、Adjust size に移動し、Resolution フィールドの値を調整します。Preview は、OK をクリックして確定する前に、結果として得られる画像サイズを推定します。
• すべての画像の幅を同じに保ってください。

スクリーンショット

技術的/チュートリアルの投稿では、例を コードブロックまたはスクリーンショットで図示してください。例には一貫性を持たせてください。例えば、手順を例示するために汎用 URL domain.com を使う場合は、一貫して投稿全体で domain.com のままにしてください。

• 静的画像は、概念を図示したり、図、UI の要素を提供したり、読者を方向づけたりするために使用すべきです。
• 画像は、誰かがコピー&ペーストできなくなるようなコマンドや設定をレンダリングするために使用すべきではありません。
• アニメーション GIF は、一定の時間または複数のアクションにわたって発生するプロセスやイベントを示す必要がある場合に控えめに使用できますが、テキストによる説明や手順を置き換えるべきではありません。
• スクリーンショットを使って、画面の特定の部分を特定し、局所化してください。そのための優れたツールがあります。例えば、Nimbus Screenshot（ブラウザ拡張機能）、Mac のスクリーンショット、Windows 向けの Snipping Tool、Ubuntu 向けの Screenshot Tool などです。

重要なセキュリティポイント: 実際のトークンやセキュリティ認証情報を使って個人情報を露出しないでください。代わりに [project's CI token] のようなプレースホルダーのスタブを使ってください。あるいは、スクリーンショットに表示される場合はぼかしてください。

ツイートや Instagram 投稿の埋め込み

ソーシャルメディアからの投稿を埋め込む手順については Markdown ガイドを参照してください。

GIF の作成

アニメーション GIF は、この種のリソースがあれば理解しやすくなるような、短い動的プロセスを図示するのに非常に役立ちます。 アニメーション GIF を作成する方法はいくつかありますが、その 1 つが Mac 向けの軽量アプリ [Giphy Capture] を使うことです。

ファイルサイズの大きい GIF は避けてください。インターネット接続が悪いユーザーにとって読み込みが困難になります。そのような場合は、GIF を小さな断片に切り分けるか、ビデオを録画するか、連続した画像を使ってください。

CMS での Author エントリーの作成

CMS（Decap）で Author エントリーを 作成する際 の一連の推奨事項を以下に示します。

• Name フィールド これは必須フィールドです。また、一意のフィールドでもあります。

  1. 執筆者の名前は、合成名を含め、姓名のみの組み合わせにすべきです。このフィールドに職務の説明（これには Role フィールドを使ってください）や英数字の組み合わせを追加しないでください。
  2. 共著者なし（例: /authors/<author1>-<author2>）。複数の単独の執筆者をブログ投稿に追加できます。個々の執筆者を作成し、それから一対多の関係として他のコンテンツタイプにそれら全員を追加すべきです。
  3. 上記と同様、単一のブログ投稿に複数の執筆者なし（例: /authors/<author1>-<author2>-<author3>-and-<author4>）。

• Role フィールド

  現在の役職または職務の説明。

• Bio フィールド

  執筆者の経歴。

• GitLab handle フィールド

  執筆者の GitLab ユーザー名（小文字形式）に対応します。このフィールドは一意である必要があります。

• Social media handles フィールド

  ソーシャルメディアのハンドル用の任意フィールド。

CMS でのブログ投稿のローカライズ

英語以外の言語でブログ投稿を公開できます。現在、以下の言語をサポートしています。

詳細については、GitLab localization チームに連絡してください。

翻訳の開始方法

ブログ投稿の翻訳プロセスを開始するのは簡単です。以下の手順に従ってください。

1. Localization プロジェクトで翻訳リクエスト Issue を作成します。プロのヒント - ブログ投稿の URL と Contentful エントリーへの直接リンクを追加してください。プロジェクトを追跡する際に非常に役立ちます。
2. Argo が英語のブログ投稿を JSON としてエクスポートし、翻訳された JSON を Contentful にインポートし直します。その後、レビューの準備が整うと Issue で ping されます。
3. ブログ投稿のエントリーに入り、翻訳されたコンテンツをレビューします。
4. 翻訳された投稿の公開について @sgittlen と調整します。
5. 公開されたら、必ず about.gitlab.com/blog/ で期待どおりに動作することを確認します。
6. 翻訳されたブログ投稿を Slack に投稿して祝いましょう。

翻訳リクエストの作成から本番への公開まで、全プロセスのビデオウォークスルーを以下に示します。

• 以下を実演するビデオ録画は近日公開予定
• Issue を作成する
• Argo のラウンドトリップ
• 翻訳が Contentful に表示される
• 翻訳をレビューする
• ライブプレビュー/言語の切り替え
• 公開する

EN ブログ投稿のローカライズ時の落とし穴

EN ブログ投稿のローカライズ時に注意すべきこと。

• slug を変更しないでください!

整理を保つためのタグ

• 投稿が翻訳中の場合は、「translation-in-progress」ラベルを付けてください。これにより、チームは翻訳・レビュー中のすべてのブログ投稿を Contentful で簡単に見つけられます。
• 投稿が翻訳された言語のローカルラベルを削除・適用してください。

  タグ	定義	使い方
  translation-in-progress	ブログ投稿が現在翻訳・レビュー中であることを示す	翻訳リクエストが開かれたときに適用する。投稿が公開されたら削除する
  language_de-DE	ドイツ語のエントリーをマークする	ドイツ語に翻訳されたブログ投稿に適用する
  language_fr-FR	フランス語のエントリーをマークする	フランス語に翻訳されたブログ投稿に適用する
  language_ja-JP	日本語のエントリーをマークする	日本語に翻訳されたブログ投稿に適用する

ページのソースコードを見る - ページの編集 - please contribute.