このページには、Google シーズンのドキュメントで受け入れられているテクニカル ライティング プロジェクトの詳細が記載されています。
プロジェクトの概要
- オープンソースの組織:
- 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 システムと、このプロジェクトの作業手順について理解を深めます。
インターンシップが開始されたら、メンターと計画の概要について話し合い、下書きを作成します。要件と必要性が判断される。最初に、ドキュメントのフローとユーザー操作プロセスの概要を説明します。その後、各セクション、カテゴリ、コンポーネントのレイアウト ワイヤーフレームについて概説します。その後、これらのレイアウトは私のメンターがレビューします。必要に応じてレイアウトが見直され、一部のコンポーネントが追加または削除されます。その後、ユーザー調査を実施して、インターフェース フローのユーザビリティと実現可能性を判断します。その後、セクションごとにドキュメント スタイルガイドを実装します（下の図を参照）。オープンソースまたはクリエイティブ・コモンズ ライセンスで利用されている他の組織によるスタイルガイドも、ガイドの追記として参照できます。この期間中にユーザビリティに問題が発生した場合は、再設計いたします。
スタイルガイドが完成して HelpHub と統合されてから、テストと最適化を実施します。脆弱性、冗長な要素、またはコンポーネントを修正します。UI とコードのテストを行い、必要に応じて望ましくないバグやエラーを修正する。完全なスタイルガイドに対して、言語、文法、スペル、句読点などの最終品質検証が実施されます。
予期せぬ遅延のために保留中のタスクは、バッファ期間内に完了します。プロジェクトの過程で実現可能と判断された追加の機能や特徴は、最終テストが完了した後に実装できます。デプロイ計画を作成し、完成品を提出します。
ツールと手法:
ドキュメントは、Google ドキュメントなどのコラボレーション プラットフォームでコンパイル、編集されます。GitHub で公開する必要がある場合は、Markdown や GitHub Flavored Markdown などのマークアップ言語も実装できます。デザインとスタイルの標準については、オープンソースのスタイル ガイドラインを参照することもできます。最後に、完成したドキュメントを WordPress を利用してフォーマットし、公開します。
コンポーネント テーブル:
スタイルガイドで実装できるコンポーネントの一覧を以下に示します。 ドキュメント ガイドライン - アクセシビリティ、ドキュメント構造、エンコード、外部ソース、事実、フォント、グローバル オーディエンス、インクルーシブ性、合法性、マルチプラットフォーム アクセシビリティ、曖昧さなし、過度な主張なし、ページ レイアウト、政治的正しさ、プロトコル、セキュリティ、文の構成、簡潔な記述、トーンとスタイル、偏り
言語と文法 - 略語と頭字語、アファメーションと否定、記事、大文字、句、直接/間接発話、一人目/二人目/三人称、性別、用語集、名詞、接頭辞、接尾辞、前置詞、代名詞、参照、スラングと専門用語、用語、単語、言い回し
句読点 - アポストロフィ、引用符、コロン、セミコロン、カンマ、省略記号、感嘆符、ハイフンとダッシュ、丸括弧、ピリオド、疑問符、スラッシュ
フォーマット - 要約、動画、要約、スクリプト、電話番号、電話番号、電話番号、スニペット、電話番号、スニペット、電話番号、電話番号、説明文、スニペット、コード ブロック、日付と時間、タイムゾーン、場所、通貨、ファイル名、脚注、見出しとタイトル、強調表示（太字、斜体、テキスト リスト、下線、取り消し線、引用、引用）
ユーザー インターフェース - アクティビティ、ボタン、コード スニペット、コードブロック、コマンドライン インターフェース、ダイアログ、メニューとプルダウン、ポップアップとアラート、タブ、用語、UI 要素、ウィンドウ
コード - CSS、HTML、JS、Markdown、MySQL、PHP、構文、XML
単語リスト/用語集 - アルファベット順（昇順）