コンテンツの質や一貫性を保つためのガイドラインです。
izanamiでは、コンテンツの質や一貫性を保つために、編集および管理の過程で一連のガイドラインや基準を設けています。このページに記載されている内容は、正しいとされる唯一の方法ではありませんが、組織や個人が採用できるコンテンツ作成ルールの一例としてご紹介します。
具体的には、文章のスタイル、許容される内容、情報の提示方法などのルールを設定し、それに従ってコンテンツを制作・公開するプロセスです。これにより、チームブログやサービス全体で、安全で統一感のある高品質なコンテンツを継続的に提供することが可能になります。
組織や個人でコンテンツ作成ルールを設けることで、読者にとって分かりやすい記事を作成することができます。このようなシステムを導入することで、記事の構成が統一され、読者がより読みやすいと感じるようになります。以下にその一例を示します。
izanami エディターには、コンテンツの質や一貫性を保つために、コンテンツガイドラインをベースにした機能が一部組み込まれています。
社内用語や略語は使わない
社内用語、略語、省略形は使用せず、フルスペルで明確に記載します。
顧客管理システム
CRM
タグは正確に表記する
タグは記事の内容を表すキーワードを設定します。特にサービス名やブランド名は正確に表記します。
- React
- Next.js
- Python
- Django
- Supabase
- react
- Next js
- パイソン
- DJANGO
- SupaBase
izanamiでは、タグを正規化する機能があります。
タイトルに使う記号を統一する
タイトルや見出しの区切りには「 : 」や「 - 」など、使用する記号の種類をあらかじめ決めて統一します。
Next.js 15 : App Router を使って Todo アプリを作成する
Next.js 15 / 【App Router】 で Todo アプリを作成する
タイトルは 8 〜 40 文字程度に
タイトルは 8 〜 40 文字程度に設定します。
Next.js 15 : App Routerを使って Todo アプリを作成する
App Routerについて
タイトルで射幸心を煽らない
射幸心を煽るようなタイトルでなく、記事の内容を読者に具体的に伝えるようにします。
SQL のデータマスキングを使って公開記事のみを表示する
これは便利！凄いツールまとめ１００選
タイトルは具体的に書く
izanamiには「利他的なコンテンツを提供する」という理念があります。
タイトルは記事に誘導させるようなものではなく、記事の内容を具体的に表すものが理想的です。サービス名やブランド名は省略せずフルスペルで正式名称を書きます。
- データベース関数と SECURITY INVOKER について
- Supabase RLS : SQL のデータマスキングを使って公開記事のみを表示する
- DaVinci Resolve を使用した映像編集の基本
- Clip Studio Paint での漫画作成 : ストーリーボードから完成まで
- Unity で 2D プラットフォーマーゲームを作成するステップバイステップガイド
- 便利過ぎる！XXXXツール200選！！
- 【無料セミナー】XXXX開発参画のコツ★
- XXXX初心者でもすぐに仕事を獲得する方法（2024年版）
- 未経験でもプロに！過剰過ぎるタイトル
- ⇨絶対に失敗しない！初心者でもできる簡単なApp開発方法❗❗
- XXXXとは？SEOを意識しすぎたタイトル
記事の要約
要約は、記事の内容、問題の解決方法を簡潔にまとめた文章です。読者が記事の要点をすぐに把握できるようにします。
izanamiでは、記事の要約をフォームから入力すると、記事の冒頭に概要を表示することができます。
Next.js 14.2.x 系で Shiki ライブラリの v1.18.0 を使用した際、一部のシンタックスハイライトがビルド後に反映されない問題は、Shiki のバージョンを 1.21.0 にアップデートすることで解消されます。
TL;DR
このような一部の人達にしか分からないインターネットスラングは、無理に使う必要はありません。リード文はわかりやすく、丁寧な表現を心がけましょう。
全角か半角かを統一
全角か半角かを統一して記号を使います。特に英語表記では半角スペースと半角記号を使い、日本語表記では全角記号を使うことを推奨します。
- Google : 英語表記に合わせて半角英数字のコロンとスペースを使用
- 日本語のサービス名：日本語に合わせて全角のコロンを使用
- Supabase: コロンの前にスペースがないため読みづらい
- Vercel：英語表記に全角のコロンを使用している
重要な部分のみ強調する
コンテンツ内の重要なフレーズには、太字を使います。文章全てには使いません。
重要な部分を太字で強調する
文章全てが強調されていると、メリハリがつかずに読みづらくなることがある。
表は視覚的な整合性を考慮する
表を使用する際は、読みやすさと視覚的な整合性を考慮します。
| 項目 | 内容 |
|---|---|
| 項目1 | 項目1の内容を解説している |
| 項目2 | 項目2の内容を解説している |
| 項目1の横幅が広過ぎる | 項目1の内容を解説していない |
| 部分的に強調する必要はない | 背景色は不要 |
| 無理に結合する必要はない。横幅を 100% にする必要もない。 | |
izanamiには、表のコンテンツに応じて横幅を自動調整する機能があります。
リンクには視覚的な差異をつける
例えば、記事中のリンクに、青色を使用し、下線をつけることで視覚的な差異が生まれ、リンクと他のテキストを区別することができます。アクセシビリティの観点から、色覚に障害がある方にも配慮するために、色だけでなく下線などの視覚的特徴も活用します。
詳細は、公式ドキュメントのJavaScript Guide (MDN)を参照してください。
詳細は、こちらを参照。
izanamiにおいてユーザーが投稿した記事では、リンクには自動的に下線が付き、青色で表示されます。リンクが視覚的に他のテキストと区別され、ユーザーに分かりやすいことが大切です。必ずしも青色や下線でなくても、リンクだとわかれば問題ありません。ただし、リンクが他のテキストと混同されないように、視覚的な差異をつけることが重要です。
引用元を明記する
引用は必ず引用元を明記し、ブロック引用を使います。
「天は人の上に人を造らず人の下に人を造らず」
青空文庫「学問のすすめ」より一部引用
「天は人の上に人を造らず人の下に人を造らず」
※引用元の情報が不足しているため、他者がその情報を検証できず、信頼性が低下する。
コードブロックの使い方
コードブロックには適切なシンタックスハイライトを設定します。
リストの使い方
箇条書きや番号付きリストは、Markdown 記法を使うことで統一されたスタイルを保持します。
- Markdown（名詞の場合は句読点をつけない）
- Markdown 記法を使ってリストを作成すること
- リストの中身が文章である場合は、適切な句読点を挿入します。
・無理に、句読点をつけない。
・並列的でない箇条書き
イメージキャプションの使い方
イメージキャプションは簡潔で、画像の目的を明確にします。
図1: システムアーキテクチャ
イメージキャプション
段落の空白は不要
段落の最初に空白を挿入しません。
この文章は段落の最初に空白がありません。
この文章は段落の最初に空白があります。
ファイル名の記述方法
ファイル名を記述する際は、コードブロック内に記載します。
ハイフンの使用を見直す
特定の状況で混乱を避けるために、ハイフンの使用を控えます。
データベース管理
データベース-管理
略称や短縮URLは避ける
フルスペルの名称や正式なURLを使い、略称や短縮URLは避けます。SSL 対応のURLが望ましいです。
https://example.com
http://ex.com
アポストロフィは使わない
不必要なアポストロフィや年代の省略形は使いません。
1980年代
1980's
表記揺れをなくす
表記揺れは、同じ意味の言葉やフレーズが異なる表記方法で使われることです。全角と半角の使い分けや、カタカナ表記の揺れなど、文中の表現が統一されていないと読者に違和感を与え、可読性が下がります。表記を統一することで、文章全体の一貫性を保ち、読みやすいコンテンツを作成することができます。
例: 「使い方」と「使用方法」のように、どちらか一方に統一します。
例: 「表記揺れ:ﾊﾞﾗﾝｽ」といったように、半角カタカナや異なる形式での表現を混ぜないようにします。
明確な見出しのヒエラルキー
見出しのヒエラルキーを深くし過ぎず、「h2 ~ h4」までを使い、情報の整理を簡潔にします。
- h2
- h3
- h3
- h2
- h3
- h3
h5, h6を使い、見出しが多層化している
リンクは過剰に使わない
リンク数を過剰にしないようにします。
必要なリンクだけを適切に使用
リンクが多すぎて、読みづらい
コンテンツのガイドライン
izanamiは、さまざまな分野のエンジニアとデザイナーが交流し、情報を共有するプラットフォームです。継続的に新しい技術を学べる場所を提供することを目指しています。プログラミング、デザイン、学術など、関心のある分野に関する作品やノウハウを発信してください。
