ブログスタイルガイド

関連ページ

• ブログハンドブック
• ブランドガイドライン

なぜブログスタイルガイドを使うのか

ブログスタイルガイドは、GitLab ブログへの投稿のスタイル、句読点、スペル、用語のガイドラインをカバーしています。スタイルガイドに含まれていないライティング、用語の使い方などについて質問がある場合は、Editorial チーム (@sgittlen) に気軽に連絡するか、提案する更新内容を含むマージリクエストを開いてチームにメンションしてください。

効果的なライティングのためのベストプラクティス

ブログ編集者は、ブログ投稿のコメントセクションで、これら一般的な成長領域のいくつかを指摘するかもしれません。以下、いくつかの留意点を紹介します:

• 「これ」「それ」で始まる文は書かないでください: 読者は何を参照しているかを見つけるために前の文に戻る必要があります。代わりに、何を言っているかを率直に定義してください。
• 読者があなたの話している内容を理解していると想定しないでください。重要な概念や用語を定義し、特定の製品やビジネスが何をしているかを説明してください。
• 関連するドキュメント、Issue、MR、過去のブログ投稿へのリンクを可能な限り追加してください。これにより、興味があれば読者がリンクをクリックして詳細を学べます。
• ブログ編集者があなたの文を 1 回以上読まなければならない場合、彼らはあなたが何を言おうとしているかについて質問するか、説明を求めるかもしれません。編集プロセスは会話であり、協調的であり、共通の理解に到達するためにいくつかの非同期のやり取りが必要になることがあります。目標は常にブログ投稿のアイデアと言語の明確さを向上させることであり、これは私たちが結果を出す のに役立ちます！

迷ったときは、ストーリーテラーではなく読者の目を持って、ドラフトをもう一度読み返してください。また、他の人が書いたものを編集することは常に簡単で、自分自身のコピーを編集することは非常に難しいです。これがピアレビュアーと編集チームの出番です！

投稿をコンテキスト化する

投稿のコンテキストを考慮することも重要です。なぜそれが読者にとって重要なのかを自問し、可能であれば、あなたのストーリーをより広い業界の問題と結びつけてください。読者になぜ興味を持つべきかをまず考え、伝えることなく、あなたが伝えたいことに飛び込まないでください。そのタイプのコンテキストは、コンテンツを「アップレベル」し、より良い読者体験につながる可能性があります。

これを行うには、一般的に 2 つの方法があります:

1. 投稿の冒頭近くにコンテキスト化のための「スイープ」パラグラフを含める

ここで何を書くべきかを決めるのに、以下のプロンプトが役立つかもしれません:

• 現状はどうですか？
• 解決しようとしている問題、または対処しようとしている課題は何ですか？
• 読者は投稿を読むことで何を得ますか？何を学びますか？

ローコード／ノーコードツールに関するこの投稿 の冒頭で、GitLab 固有のストーリーに入る前にトピックの歴史とコンテキストを示す「スイープ」パラグラフの例を見ることができます。

2. 投稿全体をアップレベルする

例: 「テクニカルインタビューの問題？ あなたが面接を受けている仕事のようではない」は、当初は GitLab の Frontend グループがテクニカルインタビューを再設計した方法についてだけのものでした。話し合いの後、ここで語るべきより広いストーリーがあると決定されました。なぜなら GitLab のストーリー（フロントエンドテクニカルインタビューの再設計）は実際には、テクニカルインタビューが効果的でなく、常に包括的ではないという、より大きく業界全体の問題に対処していたからです。

すべての投稿がこの扱いに適しているわけではないので、あなたとレビューする Editorial チームメンバーは裁量を使うことができます。場合によっては、より広くするために投稿のタイトルだけを微調整することが適切かもしれません（例: 「GitLab CI が一般的な DevSecOps の課題の解決にどう役立つか」）。

略語

頭字語または頭文字略語 を使用する場合、 最初の言及で完全な用語を使用し、直後に短縮版を括弧内に含めることを確実にしてください。それ以降は 略語または頭文字略語を代わりに使用できます。

例: A Contributor License Agreement (CLA) は、他のプロジェクトへの オープンソース貢献の業界標準です。

以下は、最初に定義する必要のないよく使われる略語と頭文字略語です（ただし控えめに使用してください。トーン・オブ・ボイス を参照）:

• AFAIK - as far as I know
• ICYMI - in case you missed it (ソーシャル専用)
• IIRC - if I recall correctly
• IRL - in real life
• TL;DR - too long; didn’t read

アメリカ英語 vs. イギリス英語

私たちはデフォルトでアメリカ英語を使用します。このリスト のスペルの違いを参照してください。

アンパサンド

会社名や出版物などのタイトルの一部である場合のみ、アンパサンドを使用してください。例: Barnes & Noble

「and」の代用として使用しないでください。

ブランチ名

ブランチの名前を書くとき、引用符やイタリック体などではなくバッククォートでスタイルするのがベストプラクティスです。例: sk-branch-name

大文字の使用

特定の単語のスタイリングについては、以下 を参照してください。

大文字小文字

すべてのタイトルと見出しには センテンスケース を使用してください。

機能名

すべての GitLab 機能名は大文字にする必要があります。GitLab 機能をワークフローの一部として参照している場合（機能自体について話しているのではなく）、小文字を使用してください。

例: 「GitLab Issue Boards は強力なプロジェクト管理およびコラボレーションツールです。」vs 「編集チームはブログ投稿の進捗を追跡するために issue board を使用しています。」

役職

役職は、人の名前の前後どちらに現れるかにかかわらず、大文字にしません。

GitLab の機能／部門／チーム

これらは GitLab という会社の組織構造 を構成する要素です。要素の名前は大文字にしますが、その後の単語は大文字にしません:

例: Engineering function、Security department

ブランド名および出版物名

ブランド名は、会社が行う方法と一貫してスタイルすることを確実にしてください。

例: WiFi Tribe、DigitalOcean

これに対する唯一の例外は、すべて大文字またはすべて小文字のブランド名です。会社のロゴでどのようにスタイルされているかに関係なく、常に最初の文字を大文字にしてください。

例: Reddit、Lego

「the」がブランドまたは出版物の名前の一部を形成する場合は、大文字にしてください:

例: The Wall Street Journal、The Times

以下のように使用される場合は、「The」を完全に削除できます:

「私たちはウォール・ストリート・ジャーナルの記者と話しました」

短縮形

私たちは、より人間的でフォーマルでなく聞こえるよう、短縮形（“can’t”、“didn’t”、“it’s”、“we’re”）を好みます。

日付

月

完全な日付を使用する場合を除き、つづりで書いてください（下記参照）。

特定の日付

Jan. 3, 2019（月を省略、3 の後に rd なし）

見出し

ブログハンドブックの見出しのアドバイス を参照してください。

リスト

Markdown で箇条書きリストを作成するには * または - を使用してください。各箇条書きの末尾にピリオドは不要です。

数字

4 桁以上の数字にはカンマを含める必要があります。

例: 2,000; 100,000

本文コピー内

1 から 9 はつづりで書いてください。10 以上には数字を使用してください。数字で文を始めるのは避けてください。やむを得ない場合は、つづりで書いてください。

見出し／小見出し内

数字を使用してください。見出しの最初にある場合は、続く最初の単語を大文字にしてください。

例: 3 Strategies for implementing a microservices architecture

代名詞

特定の誰かを指していない限り、ジェンダーニュートラルな代名詞（「they」、「them」）を使用してください。

句読点

ピリオドの後はスペース 1 つで十分です。

省略記号の後にスペース 1 つを含める（… ）

特定の単語にハイフンを入れる場合については以下 を参照してください。

私たちは em ダッシュ（—）ではなく en ダッシュ（–）を使用します。ダッシュの前後にスペースを含めてください。

常に「percent」の代わりに % を使用してください。

引用

引用符

直接引用には二重引用符を、引用内の引用には一重引用符を使用してください。一重引用符は、専門用語やことわざにも使用できます。

• ピリオドとカンマは終わりの引用符の内側に含めてください。
• セミコロン、コロン、ダッシュは引用符の外側に残してください。
• その他の句読点は、文の意味に基づいて含めてください。

例:

最近、「ソフトウェアが世界を食い尽くしている」という記事が公開されました。

「ソフトウェアが世界を食い尽くしている」という主張についてどう思いますか?

「ソフトウェアが世界を食い尽くしていることに同意しますか?」と著者は書きました。

時制

ブログ投稿にインタビュー対象者からの直接引用を含める場合、「said」「explained」などの動詞には、フィーチャージャーナリズムスタイルの現在形を使用することを好みます。

例: 「Ruby は開発者向けに最適化されており、本番環境での実行向けではない」と Sid は言います。

これの例外は、明らかに過去のイベントから引用する場合です。その場合、読者が混乱したり誤解されたりしないよう、過去形を使用してください。

インタビュー対象者の参照

ブログ投稿では、よりフォーマルでなく、私たちのトーン・オブ・ボイス に沿うため、インタビュー対象者をファーストネームで参照することを好みます。

ボイス

私たちは、ライターがブログ投稿で受動態ではなく能動態を使用することを好みます。ボイス は、文の主語が動詞のアクションを受けるか実行するかを記述します。トーン・オブ・ボイスについて、この Grammarly のブログ投稿 で詳しく学んでください。

例: 「GitLab コミュニティは 2019 年 3 月に 100 万件のマージリクエストを提出しました。」（能動態）vs.「100 万件のマージリクエストが 2019 年 3 月に GitLab コミュニティによって提出されました。」（受動態）

単語の選択

迷ったときは、単語の「未来」のスタイリングを使用してください。たとえば、「internet」は大文字にされず、「startup」はハイフン付けされません、など。

単語リスト

よく使われる単語のスペルとスタイルの方法。

• agents and flows
  • agents and flows について一般的に話しているとき、小文字を使用します。
    • 例: GitLab Duo Agent Platform agents and flows do xyz…
  • 特定の agent や flow の固有名詞について話しているときは、タイトルケースを使用します。
    • 例: The Fix Failed Pipelines Flow does xyz…
• Agile
  • Agile methodology を指す場合、A を大文字にする
• AI-powered DevSecOps platform
  • AI-powered は常にハイフン付け
  • 書面コンテンツでは powered および platform は常に小文字（デザインおよびブランドアセットで用語が使用される場合は例外あり）
  • GitLab がこの用語の前に来る場合、Platform は大文字ですが powered は大文字ではありません: GitLab AI-powered DevSecOps Platform
• all remote
  • 私たちは GitLab を all-remote 会社（remote friendly、remote first、remote only ではない）と呼びます
  • 名詞の前に出現する場合のみハイフン付け（「GitLab is an all-remote organization」／「GitLab is all remote」）
• Board
  • GitLab Board、Directors、または Board メンバーを参照する場合、Board を大文字にする
  • 一般的な board は大文字にする必要はない
• built-in/built in
  • 名詞の前に現れる場合は常にハイフン付け、例: 「GitLab has built-in CI/CD.」 動詞として使用する場合は 2 単語、例: 「GitLab comes with CI/CD built in.」
• cloud native
  • 大文字にせず、ハイフンなし。使い方に関係なく
• co-founder
  • ハイフン付け、大文字なし
• continuous delivery, deployment, integration
  • 大文字にしない
• developer
  • 「dev」という略語は控えめに使用; 大文字にしない
• DevOps
  • D と O は常に大文字
• E-Group
  • E-Group への参照は常に大文字の E、ハイフン、大文字の G を含む必要がある
• emoji
  • 単数および複数形で emoji を使用
• Git
  • 常に大文字
• GitHub
• GitLab
  • G と L は常に大文字、GitLab.com でも同様
• GitLab Self-Managed
  • self-managed GitLab、GitLab self-managed、GitLab Self-managed ではない
• internet
  • 大文字にしない
• Kubernetes
  • 常に大文字、K8s に略さない（ソーシャル以外）
• lifecycle
  • 常に 1 単語
• Master
  • この用語をブランチを指すのに使用しません…代わりに main を使用してください
• multicloud
  • 1 単語、ハイフンなし、小文字 m、小文字 c
• open source
  • 使い方に関係なく、ハイフンなし
• operations
  • 「ops」は控えめに使用; 大文字にしない
• plugin
  • 常に 1 単語
• set up/setup
  • 動詞は 2 単語、名詞は 1 単語（「How to set up a Kubernetes cluster」／「Let’s walk through the Kubernetes cluster setup process」）
• sign up/signup
  • 動詞は 2 単語、名詞は 1 単語（「Sign up for a GitLab.com account」／「Upon signup, you will be sent a confirmation email」）
• startup
  • ハイフンなし
• web
  • 大文字にしない

編集レビューチェックリスト

Diversity, Inclusion, and Belonging

私たちにはより包括的な執筆プロセスをガイドするためにブログハンドブックのライター向けチェックリスト があります。以下のチェックリストは、公開されたコンテンツが Diversity、Inclusion、Belonging (DIB) という私たちのバリューを反映するよう、編集者向けに用意されています。

画像は包括的ですか？

• 画像（カバー画像とスクリーンショット）は 包括的 ですか？
• 代替テキストは説明的ですか（SEO とアクセシビリティのため）？ そうでない場合は、著者をタグ付けするか、自分で変更してください。説明的な代替テキストを書くためのヒント を参照してください。

ライティングは包括的ですか？

• 投稿は包括的な言葉 を使用していますか？
• 投稿で取り上げられている人物が、正しい代名詞 を使用して参照されていることを確認しましたか？ 個人のチームページプロフィール と Slack プロフィールで簡単に確認できます。
• 可能な限り、文を短く簡潔に保つよう余分な単語を削除して編集してください。たとえば: 「The family is excited to buy their very own house」は「The family is excited to buy a house」に編集できます。これらの編集は、すべての読者が投稿を追いやすくします。
• ライティングがグローバルオーディエンスにとって適切であることを確認してください。地域的なメタファーや米国中心の言葉にフラグを立ててください。
• すべてのリンクが意味のある説明的なものであることを確認してください（例: 「read here」「this article」などのリンクテキストは避ける）。説明的なリンクは、スクリーンリーダーを使用する人にとってより有用でアクセシブルです。

DIB チームに尋ねる

• ブログ投稿について DIB の質問がある場合は、推測しないでください。DIB チームに連絡するか、ブログ Issue またはマージリクエストで適切なチームメンバーリソースグループ (TMRG) のリードをタグ付けしてください。

スタイルと言語

• 投稿は私たちのスタイルガイドに準拠していますか？
• アメリカ英語 で書かれていますか？
• すべてのタイトルと見出しはセンテンスケース になっていますか？

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