このページには、Google シーズンのドキュメントで受け入れられているテクニカル ライティング プロジェクトの詳細が記載されています。
プロジェクトの概要
- オープンソースの組織:
- DIPY
- テクニカル ライター:
- Areesha Tariq
- プロジェクト名:
- 大まかな再構成とエンドユーザー中心
- プロジェクトの期間:
- 標準の期間（3 か月）
プロジェクトの説明
ソフトウェア エンジニアで、テクニカル ライティングに関する専門知識があります。私には、質の高いソフトウェア ドキュメント、ユーザーガイド、マニュアル、プロジェクトの説明を執筆してきた 4 年以上の経験があります。イスラマバード、パキスタン（タイムゾーン: UTC + 5）に住んでいます。現在、Outreachy のインターンとして働いています。期間は 8 月 18 日までです。私は、組織の OpenELIS Global のテクニカル ライターとして Google ドキュメントのシーズンに参加しました。元のドキュメントはフランス語で内容が限定されており、内容も古いため、英語で広範なエンドユーザー向けドキュメントを作成しました。私は、2020 年 5 月から 8 月にかけて、Perl & Raku の Outreachy 組織に Open Food Facts サーバーのバックエンド デベロッパーとして選ばれました。バックエンド開発のほかにも、このインターンシップの主要なタスクの一つは、POD 形式でモジュールと関数のドキュメントを作成することです。 昨年、いくつかのオープンソース プロジェクトに参加したとき、オープンソースに足を踏み入れ、その後 Google ドキュメント シーズンにも参加しました。そして今年は、オープンソースとフリー ソフトウェアにおける多様性を支援することを目指す Outreachy に選ばれました。私は Git を強く信頼しています。Outreachy プロジェクトは GitHub でホストされており、3 月からは Open Food Facts と Mozilla Fenix に定期的に貢献しています。過去 3 年以上 Linux ユーザーであり、それ以来ターミナル コマンドを使用しています。
これまで使用したドキュメント ツールと言語は、Sphinx、Read the docs、Markdown です。 関連する経験があり、知識とスキルを活かして DIPY に貢献したいので、このアイデアに興味があり、取り組みたいと思っています。デジタル画像処理、コンピュータ ビジョン、ML の分野での経験があります。ニューロイメージングについての理解を深めたり、ドキュメントを作成したりできます。医療分野では豊富な経験があります。医師、患者、研究所、救急車の運転手向けに、医療に関するウェブサイトを作成しました。医師、患者、看護師、検査員、研究者が利用する別のシステムの開発に取り組みました。その方が、わかりやすいドキュメントを作成しやすくなります。
DIPY のドキュメントを確認し、ドキュメントにいくつかの欠陥を見つけました。ドキュメントに改善すべき抜け穴が複数あります。ドキュメントの現状: 特定の構造とデザインが欠けている 特に新規ユーザーにとっては操作が面倒で時間がかかる ユーザーがガイドから情報を得るのが難しい ドキュメントの内容の改善が必要 新規ユーザーとして、ユーザーガイドとデベロッパー ガイドにアクセスするのが難しいと感じたユーザーが必要な情報に簡単にアクセスできるようにドキュメントの形を変更する必要があります ドキュメントに一貫性がない
予定していること:
ドキュメント固有の構造とテンプレートを定義する ユーザーが簡単に移動して必要な情報を見つけられるようドキュメントを再形成する 今後のドキュメント作業にコミュニティを関与させるためのロードマップまたは作業項目リストを作成する ユーザーガイドおよびデベロッパー ガイドのテンプレートを定義する ユーザーガイドおよびデベロッパー ガイド用のテンプレートを定義する ユーザーガイドの書き換え、再構成、更新を行うユーザーガイド、開発ガイド、ガイドを提供する（新規ユーザーによるドキュメントの強化を支援し、テキストにドキュメントが加わりやすくなり、プロジェクトに貢献する動機付けになる）
ユーザーガイド:
ユーザーガイドでは、ユーザーが最も複雑なシステムであっても理解できるように、シンプルでわかりやすい表現を使うことを重視します。ユーザー エクスペリエンスを向上させるために、新しいユーザーが知らない可能性のある専門用語や頭字語、その他の内部情報は避けます。また、画像、注釈付きスクリーンショット、グラフィック、動画など、システムの仕組みを素早くユーザーに示すビジュアル コンテンツの使用にも焦点を当てます。適切なドキュメントを作成するには、見出しと小見出しを階層化して、各セクションで何が表示されるのかユーザーがわかるようにする必要があります。そして、ユーザーがシステムを最も有用な方法で使いこなせるように、論理的な流れに沿った階層にする必要があります。このプロジェクトの主な目標のひとつは、誰にとっても使いやすいコンテンツを作成することです。すべてのドキュメントとガイドは、一貫したスタイルに従います。複数のドキュメントで一貫したフォントと補色を使用してください。私は、ユーザーがこのシステムをうまく活用するための組織のより多くのリソースにアクセスできるようにします。
デベロッパー ガイド:
デベロッパー ガイドには、デベロッパーが DIPY のソースコードへのコントリビューションを行う際に役立つ広範なガイダンスと参考資料が含まれています。さまざまなオプションが提示されるので、目標に応じて適切なアプローチを選択できます。 開発ガイドの再構築と再構築が必要です。デベロッパー ガイドの内容を書き換えます。依存関係のビルド、コントリビューション ガイド、スタイルガイド、コーディング規則、ドキュメント ガイド、開発環境のインストール、デバッグ、テストガイド、および関連事項が含まれており、デベロッパーが簡単にアクセスできます。 熱意を持った新規のコントリビューターが初めてオープンソースに貢献しようとする際に、あなたのプロジェクトに駆り立ててくるでしょう。したがって、ガイドラインは読みやすく、詳細でフレンドリーなものになります。寄付ガイドは、ユーザーがオープンソース プロジェクトにどのように貢献できるかを説明する有用なドキュメントです。プロジェクトへの貢献は、ユーザーにとって可能な限り簡単かつ明朗なものである必要があります。次のような場合です。 修正の提出 バグの報告 メンテナンスになる コードの現状についての話し合い 新機能の提案
テンプレート
これは、寄付ガイドに使用できるテンプレートの一つです。ドキュメントの要件に応じて、変更したり、セクションを追加または削除したりできます。
DIPY への貢献
- ウェルカム メモ
TOC
行動規範
- Google の基準
- ポジティブな環境作りに貢献する行動の例
- 参加者が許容できない行為の例
- 責任
- プロジェクト メンテナンス担当者の責任
- 範囲
行動規範の対象範囲
サポートには何が必要ですか？
私たちのプロジェクトでは、[お客様のプロジェクトで使用しているプログラミング言語、フレームワーク、ツールのリストを挿入] を使用して、コードの投稿を支援しています。まだコードに貢献する準備ができなくても問題ありません。また、ドキュメントの問題 [Issue Tracker のドキュメント ラベルまたはタグへのリンク] や、[プロジェクトが設計の問題を追跡している場合は、Issue Tracker のデザインラベルまたはタグへのリンク] も確認してください。コードの投稿に関心をお持ちで、Google が利用しているテクノロジーについて詳しく知りたい方は、以下のリストをご覧ください。リソース（チュートリアル、動画、書籍）を箇条書きにまとめて、新しいコントリビューターがプロジェクトに参加するためにユーザーが知っておくべきことを把握できるようにします。
開発環境をセットアップする
このセクションでは、インストール手順とインストールする必要がある依存関係を追加します。$project をインストールするには: install project
- ソースコード: github.com/$project/$project
- Issue Tracker: github.com/$project/$project/issues
コントリビューターとしての活動
バグを報告する手順
- バグレポートを送信する前に
- （良い）バグレポートを送信する方法
変更を送信する方法
- pull リクエスト プロトコル
- チームからの回答
- 対応速度
機能強化のリクエスト方法
- 拡張機能の提案を送信する前に
- 改善の提案を（良い）送信するにはどうすればよいですか？
初めてのコードの投稿
- 初級編の問題
- サポートが必要な問題 #### pull リクエスト
- pull リクエストの作成プロセス
- すべてのステータス チェックに合格していることを確認します。
ステータス チェックが失敗した場合
- テストの作成
- テスト カバレッジ
スタイルガイド
- Git commit メッセージ
- 標準スタイル
サポート
問題がある場合はお知らせください。サポートが必要な場合は、Google のメーリング リスト（project@google-groups.com）、IRC チャット、または [プロジェクトで使用しているその他のコミュニケーション プラットフォームを記載] でお問い合わせください。
ライセンス
このセクションでは、プロジェクトのライセンスについて説明します。
所要時間とコミュニケーション:
週に 45 時間以上の勤務時間を確保しますが、万一問題が発生した場合には、週末に補償を行います。コミュニティの絆を深める期間中に、コミュニケーション手段について話し合い、メンターとの毎週のミーティング、手段、時間を決めます。メンターに最新の作業状況を伝えるとともに、詳しい作業内容をメンターにメールで知らせます。画面共有など、多くの機能が使いやすい TeamViewer を、コミュニケーションには使いたいと思っています。