Wiki貢献ガイド

以下の基準は、Wikiを一貫性のあるものに保ち、初心者にとってわかりやすく、カジュアルな貢献者にも編集しやすくするのに役立つはずです。

場合によっては例外が認められることもありますが、その際には納得できる理由が必要です。

1. 記事は読みやすく、編集しやすいものでなければなりません。シンプルな方が良いです。 記事のフォーマットは、エディターGUIで提供される基本的な機能のみを使用し、必要に応じてコードタグと表構造を追加する程度にとどめます。
   なぜか？より高度なフォーマットは、このWikiに「プロフェッショナルな」外観を与えるかもしれませんが、カジュアルなユーザーや貢献者にとっては読みにくく、編集が難しくなります。タブやボタンを使った高度なレイアウトはコンパクトですが、シンプルなレイアウトで、ただアクションやリンクのリストがある方が、ユーザーがスクロールしてクリックするだけでわかりやすいことが多いです。また、シンプルでインタラクティブでないレイアウトは印刷が簡単にできます。例えば、このチュートリアルをご覧ください: Factory install: 初めてのデバイスへのインストール。
   
   
2. このWiki内で情報を重複させないようにしましょう ： 同じトピックに関する情報は、Wiki内で 一度だけ 表示されるべきです。他の場所で必要な場合は、リンクで参照してください！
   例えば、チュートリアルを書いていて、その一つのステップが「USBストレージの設定」だった場合は、ストレージデバイスの使用にリンクするべきです。新しいチュートリアルに同じ手順を書き出したり、コピー&ペーストしてはいけません！
   
   
3. 上流のプロジェクトのドキュメントと重複させないようにしましょう ： より一般的な事項のドキュメントは、上流のプロジェクトに貢献し、それをあなたの記事にリンクすることを検討してください。このWikiはOpenWrtに関連するドキュメントのために存在しています。例えば、ipv4のようなものです。いくつかの上流のWikiの例としては、Linux WiFi drivers wikiやOpenVPN Wikiなどがあります。すべてがWikiを採用しているわけではなく、また第三者の貢献を受け入れているわけでもありません。もし上流への貢献が不可能な場合、OpenWrtのWikiにその情報を含めることは問題ありません。
   
   
4. バージョン情報を明記すること : 記事内の情報は、現在の安定版リリース に対して有効であるべきです。古いリリースやスナップショットリリース（廃止された機能や非常に新しい機能）に のみ 適用される情報は、その旨を明記する必要があります。
   
   
5. 記事は見つけやすいものにするべきです。 ほとんどの人は、自分の好きな検索エンジンやWikiの内部検索を使って情報を探します。短く、わかりやすいタイトルと導入文を使い、見つけやすいように適切なキーワードを含めましょう。好きな検索エンジンで自分の記事を検索してみてください（検索エンジンがインデックスを更新するには時間がかかるため、投稿して数日後に）。もし自分の記事が見つからなければ、他の人もおそらく見つけられないでしょう。
   例えば、installing.opkg.packages.in.mount.point.other.than.root は長いタイトルですが、opkg -- Installation Destinations のように短縮することができます。ただし、後者はWikiを直接閲覧せず、検索エンジンを使っている人にとっては、前者ほど見つけやすくはないかもしれません。
   
   
6. 記事はなぜ存在するのか、何を目的としているのかを説明すべきです。設定する機能が何であるか、指示に従うことでどのようなニーズが満たされるのかを説明する「導入」段落を1〜2つ追加してください。あまり冗長である必要はありません。例として、こちらの記事の最初の段落を参照してください: Using the Image Generator (Image Builder)
   
   
7. 記事には検証可能な情報を含め、推測はその旨を明確に示すべきです。これは、どのWikiにおいても非常に重要です。一般的な知識でない記述には出典を明記するか、出典を簡単にGoogle検索できるように十分な情報を記載してください。例として、こちらの記事を参照してください: USB 3.0 and WiFi problems
   
   
8. 執筆するすべてのチュートリアルは、必ず自身でテストするか、テストができなかった場合にはその旨を警告として明記する必要があります。誰かが成功してテストした際には、警告を削除してください。
   
   
9. 1記事につき1つのトピックに集中させる。記事は1つの具体的なトピックに焦点を当てるべきです。例えば「Adblockのインストールと設定」のようにします。Adblockやプロキシサーバー、さらにTorやVPNについても話すような「ウェブトラフィックのフィルタリング」のような、複数のトピックにまたがる一般的な記事は分割すべきです。
   
   
10. 大規模なチュートリアルは分割すべきです。各ステップが長い大規模なチュートリアルは、ステップごとに別々の記事に分け、それぞれが一部分をカバーするようにします。特に、チュートリアルが条件によって異なる手順を経たり、オプションのステップが含まれる場合は、これがさらに重要になります（例:「ステップ A を行った後、B か C のどちらかを実行し、その後 D を実行する」）。例として、Factory install: First-time installation on a device や "Hello, world!" for OpenWrt を参照してください。
    
    
11. 記事はWiki内からアクセス可能にするべきです もし記事が何らかのチュートリアルである場合は、必ずメインカテゴリーのページ（以下にリンクがあります）のいずれかにリンクを追加してください。複数の記事で構成されたチュートリアルの一部であれば、この必要はないかもしれませんが、それでもすべての記事がメインカテゴリーのページまたは他のページからアクセス可能であることを確認してください。非常に人気のある記事は、他のチュートリアル内でもリンクされることがありますが、これは上記の「このWiki内で情報を重複させない」原則の説明の通りです。現在のページにリンクしているページのリストは、右側のツールパネルにある「チェーン」アイコン（時計 アイコンの下）をクリックすると表示されます。
    
    

Wikiにより良い構造を持たせるために、「名前空間」や「カテゴリ」（および「タグ」）を使用しています:

• 名前空間 は最上位に位置します。これらの上位名前空間には、最大で3つのサブレベルが存在します。
  • about OpenWrtプロジェクトに関する全般的な情報
  • TOH 「Table of Hardware」と呼ばれる、サポート済みデバイスに関するドキュメント
  • Packages 利用可能なパッケージに関するドキュメント
  • Downloads デバイス用のファームウェアをダウンロードするためのランディングページ
  • Documentation メインドキュメントページ
  • Wiki Wikiの機能やWiki貢献ルールに関するページ
  • FAQ FAQリストを掲載する場所
  • Inbox まだ成熟していない作業中のページを置く場所
  • Playground Wiki構文を試したり、短期間で終わるようなアクションを行うための場所

• カテゴリ は名前空間の最初のレベルを提供します。これにより、異なる種類のドキュメントを区別します:
  • Quick Start 初回のインストールや設定、またはそれに類する作業のためのチュートリアル
  • User Guide ユーザー向けのドキュメントの大部分がここに入ります
  • Developer Guide 開発者向けのドキュメント

• タグ は名前空間とは異なります。名前空間は構造が排他的であり、1つのサブカテゴリにのみ記事を置くことができるのに対して、タグはもっと柔軟です。1つの記事に複数のタグを同時に付けることができ、これによりより柔軟なカテゴリ分けが可能になります。名前空間の構造で同じことをしようと思うと、異なるサブカテゴリに置かれ、1つの記事にリンクするだけの記事を書くことができますが、そういうことはしません。タグは、特定の機能を持つルーターを検索する際に最も役立つでしょう。
  • tags タグの概要

ナビゲーションを簡単にするために、sidebarを使用しています。