このページでは、Google Season of Docs に承認された技術文書作成プロジェクトの詳細について説明します。
プロジェクトの概要
- オープンソース組織:
- WordPress
- テクニカル ライター:
- tacitonic
- プロジェクト名:
- ドキュメント スタイルガイドの完全な更新版
- プロジェクトの長さ:
- 長期実行（5 か月）
プロジェクトの説明
あらすじ:
WordPress は、ユーザー補助、パフォーマンス、セキュリティ、使いやすさを重視したソフトウェアをグローバル コミュニティに提供することに専念しているグローバルな非営利ソフトウェア組織です。WordPress は、ウェブでの公開とオープンソース ソフトウェアを民主化することを目的としています。デジタル時代において、ウェブサイトは文字通り組織や個人のオンライン ファサードです。WordPress は、インターネットの 35% を占める数億人のユーザーに、そのソフトウェアで効率的にサービスを提供するという膨大なタスクを担っています。このようなユーザーにさらに効率的にサービスを提供するためには、ドキュメントが不可欠であることが証明され、ほとんどのデベロッパー、管理者、エンドユーザーによって使用されます。したがって、WordPress エコシステムの主要な要素としてドキュメントを確立できます。現在の WordPress のドキュメントには、パブリッシュに関する普遍的で統一された一連のルールとスタイルガイドラインは含まれていません。この提案は、WordPress ドキュメントに普遍的に適用できる、ドキュメント スタイル ガイドラインを一新して作成することを目的としています。このプロジェクトの目的は、セマンティクス、構文、文法ガイドライン、句読点、開発固有のルール、設計属性、フォーマットの詳細など、設計とスタイルのガイドラインのすべての側面を統合することです。また、声調、トーン、時制、すべての品詞、命名規則などの言語規則も組み込まれています。使用するツール、言語、プラットフォームは、WordPress CMS、GitHub、Markdown です。また、PHP/MySQL、HTML/CSS、JavaScript も使用できます。
プロジェクト計画:
WordPress ドキュメント スタイルガイドの現在の状況: WordPress ドキュメント チームは、未発表ながら全員一致のガイドライン公開方法を実装しています。しかし、一部の要素が前提とされている場合、プロセスは推測的になります。WordPress の記事の作成と公開には、固定の基準や条件はありません。ドキュメント チームはプロジェクト固有のスタイルガイドを作成していますが、普遍的に適用できるガイドはありません。既存のスタイルガイドのほとんどは 1 つのハンドブックに統合されておらず、非推奨で更新が必要なものです。そのため、WordPress ドキュメントを標準化するために、統一されたスタイルガイドを設計して開発する必要があります。
目標:
インターネット上のウェブサイトの 35% 以上が WordPress で運営されています。これは、何百万人ものデベロッパーとエンドユーザーが WordPress の優れた機能を利用していることを意味します。ドキュメントは、デベロッパーとユーザーが、不便な場合でも手間をかけずにこれらの機能を効率的に実行できるようにするために不可欠な要素です。このプロジェクト提案の全体的な目的は、デザインとスタイルガイドを標準化し、既存のスタイルガイドを統合して更新し、WordPress ドキュメントに新しい規制と仕様を追加することです。これにより、WordPress ドキュメントの使いやすさ、シンプルさ、統一性が向上します。
実装:
このプロジェクトのメンタリング担当者（Jon Ang）の提案に従い、このプロジェクトは、発見、定義、実装、メンテナンスの 4 つのフェーズに分けて進めることができます。プロジェクトの開始前、インターンシップ前の期間に、メンターと協力して、今後のタイムラインと成果物に沿って適切なスケジュールとタイムラインを確定します。WordPress システムとこのプロジェクトの作業手順をさらに把握します。
インターンシップが始まったら、私のメンターとプランの概要について話し合い、草案を作成します。要件と必要性が決定されます。まず、ドキュメントのフローとユーザー操作プロセスの概要を説明します。その後、各セクション、カテゴリ、コンポーネントのレイアウト ワイヤーフレームの概要を説明します。これらのレイアウトは、メンターによって確認されます。必要に応じて、レイアウトが再設計され、一部のコンポーネントが追加または削除されます。次に、ユーザー リサーチを実施して、インターフェース フローのユーザビリティと実現可能性を判断します。その後、ドキュメント スタイルガイドは、セクションごとに（下の図に示すように）実装されます。オープンソース ライセンスまたはクリエイティブ コモンズ ライセンスに基づく他の組織のスタイルガイドを参照して、Google のガイドに追加することもできます。この期間中にユーザビリティの問題が発生した場合は、再設計いたします。
スタイルガイドが完成し、HelpHub と統合されると、テストと最適化が行われます。脆弱性、冗長な要素やコンポーネントは修正されます。UI とコードのテストが行われ、不要なバグやエラーが修正されます（必要に応じて）。言語、文法、スペル、句読点などについて、完全なスタイルガイドの最終品質管理を行います。
予期しない遅延により保留中のタスクは、バッファ期間内に完了します。プロジェクトを進める過程で実現可能と判断された追加の機能や特徴は、最終的なテストが完了した後に実装できます。デプロイ計画が作成され、完成品が提出されます。
ツールと方法論:
ドキュメントは、Google ドキュメントなどの共同編集プラットフォームでコンパイルおよび編集されます。GitHub で公開する必要がある場合は、Markdown や GitHub Flavored Markdown などのマークアップ言語も実装できます。デザインとスタイルの標準については、オープンソースのスタイルガイドも参照できます。最後に、完成したドキュメントをフォーマットし、WordPress を使用して公開します。
コンポーネント テーブル:
以下に、スタイルガイドで実装できるコンポーネントの一覧を示します。ドキュメントのガイドライン - ユーザー補助、ドキュメントの構造、エンコード、外部ソース、事実、フォント、世界中の視聴者、包括性、合法性、マルチプラットフォームのユーザー補助、あいまいさのない表現、過度な主張の排除、ページ レイアウト、ポリティカル コレクトネス、プロトコル、セキュリティ、文の構造、簡潔な文章、トーン / スタイル、偏見のない表現
言語と文法 - 略語と頭字語、肯定と否定、冠詞、大文字、節、直接話法/間接話法、一人称/二人称/三人称、性別、用語集、名詞、接頭辞と接尾辞、前置詞、代名詞、参照、スラングと専門用語、スペル、専門用語、時制、動詞、態
句読点 - アポストロフィと引用符、コロンとセミコロン、カンマ、省略記号、感嘆符、ハイフンとダッシュ、丸括弧、ピリオド、疑問符、スラッシュ
書式設定 - 要約、導入、序文、ブランド名、商品名、キャプション、コード スニペット、コードブロック、日時、タイムゾーン、場所、通貨、ファイル名、脚注、見出しとタイトル、ハイライト表示（太字、斜体、下線、取り消し線、引用符）、インデント、索引、リンクと URL、リスト、箇条書き、番号付け、メディア（画像、動画）とイラスト、注、警告、ヒント、数値と電話番号、多言語、翻訳、言語の文字、スペース、表、テキスト、商標、著作権、特許、引用、チュートリアルと手順、UI 要素、測定単位
ユーザー インターフェース - アクティビティ、ボタン、コード スニペット、コードブロック、コマンドライン インターフェース、ダイアログ、メニューとプルダウン、ポップアップとアラート、タブ、用語、UI 要素、ウィンドウ
コード - CSS、HTML、JS、Markdown、MySQL、PHP、構文、XML
用語辞典/用語集 - A ～ Z