原文: The freeCodeCamp Publication Style Guide
(訳注: このガイドは英語版のオリジナル記事執筆者向けのガイドを元に日本語用の内容を加えたものです。)
あなたのノウハウや知識を freeCodeCamp コミュニティのためにシェアしてくださることに感謝します。
freeCodeCamp ニュースを通して、世界中のデベロッパーやデザイナー、データサイエンティストに向けて教えることができます。
ウェブ上で最も訪問者数の多い技術系サイトの一つとして、freeCodeCamp.org は、あなたの知識を必要としている人々に届けられるようお手伝いします。
また、freeCodeCamp は優れたソーシャルメディアでの知名度、アクセシビリティ、SEO も強みとしており、真剣に学びたい人のための学習リソースとして定評があります。これらの点はすべて、あなたの記事の読者を増やすことにつながるでしょう。
このスタイルガイドでは、あなたのチュートリアル記事に説得力を持たせ、影響力を最大化するコツを解説します。
freeCodeCamp ニュースは「blog-a-day (一日一記事)」のようなチャレンジに取り組む場所や、「stream-of-consciousness (意識の流れ)」を描写するような記事を投稿する場所ではありません。
事実に基づき、引用や、コードスニペットや、データ可視化を活用して、記事を作成してください。
何年にも渡って蓄積したデータによれば、より詳細なチュートリアルほどより長い時間読まれ、そして読者が周りに共有する可能性も高くなります。
あなたが選んだトピックについて、最低 500 ワード (訳注: 1 ワード約 2.5 文字として換算すると、日本語の場合約 1250 文字) の内容が書けないようであれば、まずはもっとリサーチをすることから始めましょう。
より深く、より広くリサーチすることで、読者により多くの知識を提供できるようになるでしょう。
人々は忙しいのです。ですから、あなたは即座に読者の注意を引かなければなりません。ではどうすればいいのでしょう？そのために、説得力のあるタイトルが必要です。
記事タイトル: あなたのチュートリアルの中で唯一 100% の人が読む部分
本文を書き始める前に、説得力のあるタイトルを考える時間をとってください。そうすると、チュートリアル全体をそのタイトルを起点に書き始め、またそのタイトルに立ち返って説得力を持たせることができます。
過去 7 年間、私たちはさまざまなフォーマットを試してきました。そして世界中の開発者に最も読まれるのは深い内容の技術的なチュートリアルだと判明しました。
以下は、チュートリアル記事の効果的なタイトルの例です:
- 「…の修正方法」(How to fix…)
- 「…の作成方法」(How to build…)
- 「… [ツール] で～ [タスク] をする方法」(How to [task] with [tool])
- 「…の仕組み」(How [something] works)
- 「…するための～なガイド」(The [adjective] guide to…)
- 「… [名詞] とは？」(What exactly is [noun]?)
- 「…が重要な理由」(Why [something] matters.)
- 「…の歴史」(A history of [something])
- 「…ハンドブック」(The [something] Handbook) ※最低 2 万ワード (日本語で約 5 万文字) 以上の長いチュートリアル用
カバー画像の追加
明確でわかりやすいタイトルを付けたら、次は良いカバー画像を追加しましょう。Ghost のエディター画面右上の、歯車のアイコンをクリックしてください。
中には自分でカバー画像を作成するコントリビューターもいます。Canva.com などの無料のサイトで作成することもできます。(Twitter や LinkedIn で記事がシェアされたときに画像の端が切れるのを避けたい場合は、アスペクト比 1.91:1 の画像を使用してください。)
カバー画像を作成する場合に注意してほしい点がいくつかあります。
- 適切なコントラストの色を使用し、画像 / テキストが目立つようにしてください。
- 画像内に文字を入れすぎないように、メインのテーマ / キーワードに集中してください。(例えば "How to Build a Food Ordering App with React" というテキストを全部入れ込むより、"How to Build an App with React" や "Build a React App" の方が良いでしょう。)
- 一般的に、カバー画像はシンプル・イズ・ベストです。小さなデバイスでも見やすいような、目を引く画像が良いでしょう。
- ライターとしてのあなたの「ブランド」を確立するためにカバー画像を役立てることもできます。デザインに統一性のある画像を作成することで、次第に読者がカバー画像を見ただけであなたの記事だとわかるようになります。
使える画像がない場合、Pexels、Unsplash、Wikipedia などのサイトからクレジット表記不要の画像をダウンロード・保存して、Ghost にアップロードすることもできます。
外部の画像に直リンクはしないでください。代わりに、使いたい画像をダウンロードし、Ghost のエディターにドラッグ & ドロップで追加してください。これで freeCodeCamp の CDN を通してイメージを提供でき、パフォーマンスとアクセシビリティが向上します。画像サイズは 1MB 以下に収めるよう心掛けてください。
記事の URL の設定
記事の URL はコントリビューターが直接編集できます。「machine-learning-with-pytorch-tutorial」や「how-to-push-to-git-remote-repository」のように、短く説明的なものにすることをお勧めします。
(訳注: 翻訳の場合は、原文の記事と同じ設定にしてください。)
タグの選択
記事には 1～5 個のタグを付けられます。どのようなタグを付けたいか選んで編集チームにお知らせいただければこちらで追加します。(訳注: 翻訳記事の場合は、原文を元に編集チームで選んで設定します。)
このタグにより、検索やタグの一覧を通して読者が記事を見つけやすくなります。
1 番目のタグが最も重要で、記事の上部に表示されます。
その他のメタ情報は変更しないでください。適切なデフォルト値が設定されていますので、そのままにしてください。
本当に読まれるチュートリアルを書くためのヒント
文法、スペル、書式は重要です。
記事が適切にわかりやすく整形されていれば、より読みやすくなります。以下は記事をできるだけ読みやすくするためのヒントです。
- シンプルにしましょう。できる限りシンプルで簡単な言い回しを使ってください。
- 文を短くしましょう。長い文は短く分けてください。その方が読者にとって速く読めてわかりやすくなります。
- 段落を短くしましょう。長い段落は一、二文ずつの段落に分割してください。壁のようなテキストを見たら、読者は記事を読む気をなくしたり、斜め読みで済ませようとしてしまうでしょう。
- 句読点を整理しましょう。こんな風に感嘆符を使いすぎると気が散ります！！！セミコロンが必要なことはめったにありません; シンプルにピリオドで文を終えてください。そして三点リーダーは…ええと…おそらく余計です。
- サブ見出しを利用して文章を構造化しましょう。Ghost では大小 2 種の見出しのサイズが用意されています。メインのトピックには大きい見出し、その中のセクションには小さいサブ見出しを使用してください。
- 太字、斜体、またはその両方の過度な使用は避けましょう。文字装飾を使いすぎると読みづらくなります。太字と斜体を同時に使った場合は特にです。太字と斜体は別々に、そして控えめに使用してください。
- 略語は避けてください。略語はチュートリアルをわかりづらくします。広く知られていない頭字語 (英語における、頭文字をつなげた略語) は、略さず書きましょう。ラテン語由来の「e.g.」「… etc.」のような表記は「例えば」「…など」に置き換えましょう。
自分でも校正しましょう。そして更にもう一度校正しましょう。
アイデアを書き留めるために素早く記事を書くコントリビューターもいます。一方、最初の一文字を書き始める前に徹底的にリサーチをするコントリビューターもいます。
あなたの執筆プロセスがどうであれ、必ず一度記事から離れ、初めて読むつもりで戻ってきてください。
記事をもう一度読み直しましょう。それから声に出して読んでみてください。ちょっとした間違い、誤字、おかしな言い回しに気付いて驚くことでしょう。
コードにシンタックスハイライトを追加しましょう。
Ghost のエディター上でバッククォートを 3 つ (```) 入力して、スペースキーを押すと、コードブロックを作成できます。
プログラミング言語を指定してシンタックスハイライトを使うこともできます。
例えば、```js と入力すると JavaScript の構文に合わせてシンタックスハイライトが適用されます。他にも多くの主要なプログラミング言語のシンタックスハイライトがサポートされています。
話が本筋からそれないようにしましょう。
読者の時間は有限です。読者が次の用事に移らざるを得なくなる前に、あなたの記事からできるだけ多くの価値を得られるようにしてください。
できる限り段階的なチュートリアルにしましょう。
- 読者にその記事で得られることを伝える簡潔な導入部を書きます。
- このような番号付きのリストを使って手順を示します。
- できる限り詳しい情報を詰め込みます。
- まとめとして読者が得たものを再度伝えて締めくくります。
複数回に分かれたチュートリアルより、長く包括的なチュートリアルを書く
シリーズの第 2 回、第 3 回、第 N 回の記事があっても、それ以前の記事を読んでいない読者は読もうとしないのを何度も見てきました。
それと同時に、非常に長く詳細なチュートリアルが、驚くほどよく読まれるのも見てきました。読者はそのチュートリアルをブックマークしたり、ソーシャルメディアでシェアしたりして、後で読み返せるようにするのです。
長いチュートリアルを見た人は、それが真面目で幅広い内容であると予想します。そして、じっくりと時間をかけて読むようになります。更に自宅でコードエディターを開いて手を動かしながら読む人も多くいます。
全年齢対象の表現を用いる
freeCodeCamp コミュニティメンバーは成人が大半ですが、子供もいます。
引用文でない限り、罵り言葉 (profanity) は使用しないでください。また、不快に感じる可能性があるミームは避けてください。
最後に、記事が freeCodeCamp の行動規範に違反していると見られる場合、freeCodeCamp は即座に記事を削除します。ただしその場合も作業内容が失われることのないよう、記事のバックアップを取り、個人の記録用として著者に送信します。
クレジット表記不要、または自分で作成した画像を使う
自分で作成した画像やスクリーンショットは記事に含めて構いません。権利を有していない写真の場合、似たような画像でクレジット表記不要な物を使用してください。そうすればライセンス料やクレジット表記の必要はありません。
そのような画像を見つけられるウェブサイトとして、Pexels、Unsplash、Wikipedia などがあります。
繰り返しになりますが、外部の画像に直リンクはしないでください。代わりに、使いたい画像をダウンロードし、Ghost のエディターにドラッグ & ドロップで追加してください。これで freeCodeCamp の CDN を通してイメージを提供でき、パフォーマンスとアクセシビリティが向上します。画像サイズは 1MB 以下に収めるよう心掛けてください。
一部のウェブコミックなど、共有を念頭において作成されている画像があります。これらについては、画像を挿入した後に「画像: XKCD」のようにクレジット表記と引用元ページへのリンクを追加してください。
かならずソースを明記し、盗作をしない
盗作とは、他人の文章 (または画像、コード、その他) を自分の物と偽ることです。盗作は重大な犯罪であり、退学、退職などの処分となり得る行為です。freeCodeCamp ニュースにおいても同様に深刻な問題と捉えています。
freeCodeCamp ニュースにおいて盗作を試みた人はこれまでほとんどいませんが、残念ながら 7 年間で数人存在しました。私たちはその人物を突き止め、記事を削除し、コミュニティから追放しました。
また、誤って盗作してしまうことはないので安心してください。盗作とは意図的に行われる行為です。
ソースを適切に引用する方法
他の記事や、動画、講座、またはその他のメディアで誰かが言ったことを言い換える場合 (または直接引用する場合)、その人物をクレジット表記してください。これは、下記のように元のソースへのリンクを追加することと、プルクオートの書式を使用することを意味します。
"This game is controlled entirely by typing into a command line interface. Because the game is real-time in nature, this can lead to some intense moments of rapidly typing commands as you try to save your drones from danger." (Source: Quincy Larson)
これは、公式ドキュメント、StackOverflow、GitHub、およびその他の同様のリソースから取得したテキスト (あるいはコード) も対象です。そのようなソースから何かをコピー & ペーストする場合、必ず引用元を明記してリンクしてください。
引用は常に、それを最初に発言した人に帰属させてください。複数行の引用文の場合、下記のようなプルクオートを使用して長い段落を分割できます。
“When you have wit of your own, it’s a pleasure to credit other people for theirs.”
― Criss Jami
あなたのコードが他人のコードに強く影響を受けている (あるいは他人のコードを借用している) 場合は、その人をクレジットする必要があります。
他の人の作品に大きく依存するチュートリアル記事を投稿する前に「この記事は元の作品を十分に拡張しているか？」と自分自身に問いかけてみてください。答えが NO であれば、正当な記事とは言えないかもしれません。
他人の言葉を使用する際の最後の注意点として、できれば自分の言葉を使用することをお勧めします。過度に他の情報源を引用したりコピー & ペーストしたりせず、情報を噛み砕いて、自分の言葉で説明してください。そうすることで理解を深めることにも役立ち、他人の作品を盗用するリスクもなくなります。
どうしても他のソースから引用または借用する必要がある場合には、必ず適切に引用してください。
盗作の例
以下は盗作、つまりしてはいけないことの例です。一つ目の例は明確にわかるはずです。(一言一句コピーされています):
元のテキスト:
Just a quick note before we get started: Instagram's desktop interface and mobile app are quite different. Most people use Instagram on their mobile device (from the Instagram app) because that's where you can actually post photos. (Source: Abbey Rennemeyer)
盗用されたテキスト:
Ok, everyone ready to learn about Instagram? Let's dive in!
Just a quick note before we get started: Instagram's desktop interface and mobile app are quite different. Most people use Instagram on their mobile device (from the Instagram app) because that's where you can actually post photos.
Now that we have that out of the way, we're ready to go.
ご覧の通り、盗用されたテキストは独自のテキストに挟まれています。他の誰かが上手に書いたフレーズや段落を使いたくなるものです。しかし、その部分を正しく引用しなければ、それは盗作です。
二つ目の例は、それほど目立たないかもしれません。しかし他の誰かの言葉をほとんど真似て言い換えているのなら、それも盗作です。
元のテキスト:
There are many reasons you might want to share photos and videos on Instagram.
Perhaps you're starting a business or launching a product. You might work for a company that wants to have an Instagram presence. Maybe you want to build your personal brand as a photographer, traveler, or artist. Or you just want to share what you're into right now via pictures.
Whatever the reason, Instagram is a great place to share ideas, messaging, and art online. (Source)
盗用されたテキスト:
There are lots of reasons to share photos and videos on Insta.
Maybe you're starting your own business or launching some product. Maybe you work for an organization who wants to have an Instagram presence. Or maybe you want to create your own brand. Or you just want to show what you're doing now in pictures.
Either way, Instagram is a great place to post those ideas, messages, and art online.
ご覧の通り、上記のテキストはかなり元のテキストに基づいています。いくつか変更したり、省略した単語もありますが、この人が自分で書いたものではないことは明らかです。これも許容されず、盗作と見なされます。
何が盗作となるか疑問に思っているなら、リサーチをして、必ず適切な引用方法を理解してください。そしてあなたオリジナルの作品を作り上げてください。
クロスポスティングは避ける
クロスポスティングは一般的に効果がありません。多くの人に記事を読んでもらいたいなら、その記事は 1 つの場所で公開することをお勧めします。公開する場所は freeCodeCamp ニュースでも、個人ブログでも、オンラインマガジンでも構いません。
ただしいくつか例外があります。
- Google によってインデックスされていないサイト内の記事はクロスポストする価値がある可能性があります。
- あなたの雇用主となる可能性がある人に見せるために、他の場所で公開した自分の記事を個人ブログで紹介する場合、自分のブログにクロスポストしてカノニカル URL を元記事に向けて設定すると良いでしょう。これにより Google が混乱して誤ったバージョンを検索結果に表示する可能性を減らせます。
また、個人ブログの似たテーマの記事 (例えば「Visual Studio プラグイン」「高度な Bash コマンド」など) を集めて 1 つの長いチュートリアル記事として freeCodeCamp ニュースで公開することは可能です。
私たち編集チームはあなたの記事について指導したり、細心の注意を払って編集したり、広大な freeCodeCamp コミュニティに向けて広めたりすることにたくさんの時間を費やすつもりでいます。そのため原則として、Medium のように誰でも投稿可能なオープンなサイトにクロスポストしないようお願いしています。
記事内のセルフプロモーションの許容範囲
freeCodeCamp.org は寄付によって支えられている非営利団体です。私たちは有料のプロモーション記事を配信していると思われたくはありません。(実際行っていません。) そのような印象を受けると、寄付を思いとどまる人がいるかもしれないからです。
同時に、あなたが自分の最新の本、講座、SaaS アプリケーションを広めたり、メーリングリストの登録者や Twitter のフォロワーを増やしたりしたいケースがあることも十分理解しています。
セルフプロモーションはできるだけ控えめにお願いします。記事の最後にアクションを促す一文を含める程度であれば全く問題ありません。
チュートリアルの書き始めにあなたの製品へのリンクを置かないでください。スパムのように見える可能性があります。また、個人で作成した書籍やコースへのリンクでない限り、アフィリエイトリンクは使用しないでください。
また、ブランドアカウントは許可していません。ゴーストライティングは一切禁止します。また、ある会社の従業員から別の従業員へ記事を移行することもありません。
そして、まだ freeCodeCamp コントリビューターアカウントを取得していない他の人に代わって記事を書くことはおやめください。
あなた自身のサイトの SEO のために覚えておいてほしいことがあります。一般的な他のウェブサイトと異なり、freeCodeCamp ニュース内ではすべてのリンクが rel="doFollow" に設定されています。つまり、あなたがリンクしたリンク先のページ (あなたの個人ブログを含む) は、Google のランキングで良い影響を受けます。このことを頭に入れた上で、やりすぎないようにしてください。
最後の仕上げ
記事を読者に届ける準備ができたと確信したら、下書き (Draft) のエディター画面へのリンクを Trello に記入し、レビューを依頼してください。(訳注: 英語チームではメールを使用しています。英語版のフローは原文を参照してください。) 編集チームが記事を確認し、よりよくするために必要な編集を加えてから公開します。
私たちが気にする主な点は、タイトルと冒頭の段落です。書式の問題や文法の誤りを見つけた場合、そのような点も修正します。
まだかなり改善が必要であると感じた場合には改善点をご連絡しますので、修正後、再度提出してください。
最後に重要な注意点があります。もし企業から報酬を得て、freeCodeCamp ニュース用に記事を作成・投稿するよう依頼されている場合には、編集チームに下書きを提出する際にその事実を開示してください。
その他のヒント
GitHub Markdown
GitHub-flavored Markdown を使って記事を書くこともできるとご存じでしたか？
Markdown をエディターに貼り付けると、リッチテキストに変換されます。
また、Markdown 構文 (# や ## で見出し、* で箇条書き) を行の先頭に入力してから続きを書くことで、テキストを指定の書式に変更できます。
埋め込みコンテンツは控えめにする
必要に応じて、ツイートや YouTube 動画などを埋め込むことが可能です。新しい行の先頭の＋アイコンをクリックすると、さまざまな埋め込みツールを選択できます。
とはいえ、以下 3 つの理由から、埋め込みコンテンツは控えめに使うことを推奨します。
- 埋め込みコンテンツは Twitter などの外部サービスと通信し、動作が遅くなる可能性があります。
- スクリーンリーダーを使って記事を読んでいる読者も多数います。開発者コミュニティの大部分の人が視覚障害を抱えていたり、全盲であったりします。埋め込みコンテンツはテキストよりもアクセスしづらくなります。
- 各記事には AMP (Accelerated Mobile Pages) バージョンが存在します。埋め込みコンテンツは AMP では正しく表示されない可能性があります。
まだコントリビューターアカウントをお持ちでない場合は、こちらから申し込みが可能です。
freeCodeCamp コミュニティに知識を共有してくださりありがとうございます
このガイドがより良い記事の作成に役立ち、あなたの知識がコミュニティ全体の役に立つことを願っています。
Happy coding!
— freeCodeCamp 編集チーム