ブログスタイルガイド
関連ページ
なぜブログスタイルガイドを使うのか
ブログスタイルガイドは、GitLab ブログへの投稿のスタイル、句読点、スペル、用語のガイドラインをカバーしています。スタイルガイドに含まれていないライティング、用語の使い方などについて質問がある場合は、Editorial チーム (@sgittlen) に気軽に連絡するか、提案する更新内容を含むマージリクエストを開いてチームにメンションしてください。
効果的なライティングのためのベストプラクティス
ブログ編集者は、ブログ記事のコメント欄でこれらの一般的な改善点を指摘することがあります。覚えておくべき項目をいくつか紹介します。
- 文を「This」や「That」で始めない: 読者が前の文に戻って何を参照しているのか確認しなければなりません。代わりに、伝えたいことを明確に定義してください。
- 読者があなたの言っていることを知っていると仮定しない。重要な概念や用語を定義し、特定の製品やビジネスが何をするのかを説明してください。
- 可能な限り、関連するドキュメント、Issue、MR、または過去のブログ記事へのリンクを追加してください。これにより、読者が興味を持った場合にリンクをクリックしてさらに学ぶことができます。
- ブログ編集者があなたの文を複数回読む必要がある場合、彼らは何を伝えようとしているのか質問したり、説明を求めたりするかもしれません。編集プロセスは会話でありコラボレーションであり、共通の理解に到達するために数回の非同期のやり取りが必要になる場合があります。目標は常にブログ記事のアイデアと言語の明確さを向上させることであり、それが私たちが結果を出すのに役立ちます！
迷ったら、今度はストーリーテラーではなく読者の目で、もう一度下書きを読み直してください。また、自分のコピーを編集するよりも、他の人が書いたものを編集する方がはるかに簡単です。これがピアレビュアーと Editorial チームの出番です！
投稿に文脈を持たせる
投稿の文脈を考慮することも重要です。なぜそれが読者にとって重要なのかを自問し、可能であれば、あなたのストーリーをより広い業界の問題と結び付けてください。読者が興味を持つべき理由について最初に考え、伝えることなく、読者に伝えたいことに直接飛び込むことは避けてください。そのような文脈はコンテンツを「アップレベル」し、より良い読者体験につながります。
これには通常 2 つの方法があります。
1. 文脈を提供するために投稿の冒頭近くに「スイープ」段落を含める
以下のプロンプトは、ここで何を書くべきかを判断するのに役立つかもしれません。
- 現状はどうですか？
- どのような問題を解決しようとしていますか、またはどのような課題に取り組みたいと考えていますか？
- あなたの投稿を読むことで、読者は何を得られますか？何を学べますか？
「スイープ」段落の例は、ローコード/ノーコードツールに関するこの投稿の冒頭で見ることができ、GitLab 固有のストーリーに飛び込む前にトピックの歴史と文脈を提供しています。
2. 投稿全体をアップレベルする
例: 「技術面接の問題点とは？面接対象の仕事と異なる」は、もともと GitLab のフロントエンドグループが技術面接をどのように再設計したかについてだけのものになる予定でした。議論の結果、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 are a powerful project management and collaboration tool.」 vs 「The editorial team uses an issue board to track the progress of blog posts.」
役職名
私たちは役職名を、人の名前の前後に表示されるかどうかにかかわらず、大文字にしません。
GitLab の機能/部門/チーム
これらは GitLab という会社の組織構造を構成する要素です。要素の名前は大文字にしますが、その後の単語は大文字にしません。
例: Engineering function、Security department
ブランド名と出版物名
ブランド名は、その会社のスタイル設定と一致するようにスタイル設定してください。
例: WiFi Tribe、DigitalOcean
これに対する唯一の例外は、すべて大文字またはすべて小文字のブランド名です。会社のロゴでどのようにスタイル設定されていても、常に最初の文字を大文字にしてください。
例: Reddit、Lego
「the」がブランドや出版物の名前の一部を形成している場合は、大文字にしてください。
例: The Wall Street Journal、The Times
以下のように使用される場合、「The」を完全に省略することができます。
「We spoke to a Wall Street Journal reporter」
短縮形
私たちは、より人間的でフォーマルでない響きにするために、短縮形（「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 つ含めます。
特定の単語をハイフンでつなぐタイミングについては以下を参照してください。
エムダッシュ（—）ではなく、エンダッシュ（–）を使用します。ダッシュの前後にスペースを含めます。
「percent」ではなく常に % を使用します。
引用
引用符
直接引用にはダブルクォーテーションマークを使用し、引用内引用にはシングルクォーテーションマークを使用します。シングルクォーテーションマークは、専門用語やことわざにも使用できます。
- ピリオドとコンマは終了引用符の内側に含めます。
- セミコロン、コロン、ダッシュは引用符の外側に置きます。
- 文の意味に基づいて他の句読点を含めます。
例:
Recently, an article was published stating, “Software is eating the world.”
What do you think of the claim, “Software is eating the world”?
“Do you agree that software is eating the world?” wrote the author.
時制
ブログ記事にインタビュー対象者からの直接引用を含める場合、「said」、「explained」などの動詞には、特集ジャーナリズムスタイルの現在形を使用することを好みます。
例: “Ruby was optimized for the developer, not for running it in production,” says Sid.
これに対する例外は、明らかに過去のイベントから引用する場合です。その場合は、読者が混乱したり誤解されたりしないように、過去形を使用してください。
インタビュー対象者の参照
ブログ記事では、インタビュー対象者を名前で参照することを好みます。これは、よりフォーマルでなく、私たちのトーン・オブ・ボイスに沿っているからです。
態
私たちは、ブログ記事ではライターが受動態ではなく能動態を使用することを好みます。態は、文の主語が動詞の動作を受けるか、実行するかを表します。トーン・オブ・ボイスについてはGrammarly のこのブログ記事で詳しく学んでください。
例: “The GitLab community submitted 1 million merge requests in March 2019.” (能動態) vs. “One million merge requests were submitted by the GitLab community in March 2019.” (受動態)
単語の選択
迷ったら、単語の「未来形」スタイル設定を使用してください。例えば、「internet」は大文字にせず、「startup」はハイフンでつながず、などです。
単語リスト
よく使う単語のスペルとスタイル設定。
- agents and flows
- エージェントとフローを一般的に話す場合は、小文字を使用します。
- 例: GitLab Duo Agent Platform agents and flows do xyz…
- エージェントとフローの固有名詞について話す場合は、タイトルケースを使用します。
- 例: The Fix Failed Pipelines Flow does xyz…
- エージェントとフローを一般的に話す場合は、小文字を使用します。
- Agile
- アジャイル方法論を指す場合は 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
- 大文字にしません
Editorial レビューチェックリスト
ダイバーシティ、インクルージョン、ビロンギング
私たちは、より包括的なライティングプロセスをガイドするためのブログハンドブックのライター向けチェックリストを持っています。以下のチェックリストは、編集者が公開されたコンテンツがダイバーシティ、インクルージョン、ビロンギング (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) のリーダーにタグを付けてください。
