このページでは、Google Season of Docs に承認された技術文書作成プロジェクトの詳細について説明します。
プロジェクトの概要
- オープンソース組織:
- DIPY
- テクニカル ライター:
- Areesha Tariq
- プロジェクト名:
- 高度な再構成とエンドユーザー フォーカス
- プロジェクトの長さ:
- 標準期間（3 か月）
プロジェクトの説明
ソフトウェア エンジニアで、技術的な文章作成の専門家です。質の高いソフトウェアのドキュメント、ユーザーガイド、マニュアル、プロジェクトの説明の作成に 4 年以上携わっています。パキスタンのイスラマバードに住んでいます（タイムゾーン: UTC + 5）。現在、Outreachy でインターンとして働いており、8 月 18 日まで継続する予定です。 私は、OpenELIS Global という組織のテクニカル ライターとして、Google Season of Docs に参加しました。元のドキュメントがフランス語で、内容が限られていて、古いため、英語で広範囲かつ最新のエンドユーザー向けドキュメントを作成しました。2020 年 5 月から 8 月の Outreachy で、Perl & Raku 組織の Open Food Facts サーバーのバックエンド デベロッパーとして選ばれました。このインターンシップの主なタスクの一つは、バックエンド開発に加えて、モジュールと関数のドキュメントを POD 形式で作成することです。私は昨年、いくつかのオープンソース プロジェクトに貢献し、その後 Google Season of Docs に参加したことで、オープンソースの世界に足を踏み入れました。そして今年、オープンソースとフリーソフトウェアの多様性をサポートする Outreachy に選ばれました。Outreachy プロジェクトは GitHub でホストされているため、Git を熟知しています。3 月から Open Food Facts と Mozilla Fenix に定期的に貢献しています。過去 3 年以上 Linux ユーザーであり、それ以来ターミナル コマンドを使用しています。
私が使用したドキュメント ツールと言語は、Sphinx、Read the docs、Markdown です。このアイデアは魅力的であり、関連する経験があり、自分の知識とスキルを DIPY に貢献したいと考えております。デジタル画像処理、コンピュータ ビジョン、機械学習の分野で経験があります。神経画像をより深く理解し、ドキュメント作成に役立てることができます。私は医療分野で豊富な経験を積んでおります。医師、患者、研究所、救急車の運転手向けの医療ウェブサイトを開発しました。私は、医師、患者、看護師、ラボアシスタント、研究者が使用する別のシステムに携わっていました。視聴者が理解しやすいドキュメントを作成できます。
DIPY のドキュメントを確認したところ、ドキュメントにいくつかの欠陥があることがわかりました。ドキュメントには複数の抜け穴があり、改善する予定です。ドキュメントの現状: ドキュメントに特定の構造と設計がない 特に新規ユーザーにとって、ナビゲーションが面倒で時間がかかりすぎる ユーザーはガイドから情報を入手するのが難しいと感じている ドキュメントの内容を改善する必要がある 新規ユーザーとして、ユーザーガイドとデベロッパー ガイドにアクセスするのが難しいと感じました。ユーザーが必要とする情報に簡単にアクセスできるように、ドキュメントを再構成する必要がありますドキュメントに整合性がありません
次の対応を予定しています。
ドキュメントの特定の構造とテンプレートの定義 ユーザーが必要な情報を簡単に検索できるようにドキュメントを再形成する 今後のドキュメント作業にコミュニティを関与させるためのロードマップまたは作業項目リストを作成 ユーザーガイドとデベロッパー ガイドのテンプレートを定義する 貢献ガイドのテンプレートを定義する 新しいドキュメントの書き換え、再構成、更新
ユーザーガイド:
ユーザーガイドでは、複雑なシステムでもユーザーが理解できるように、シンプルでわかりやすい言葉を使うようにします。新しいユーザーが知らない可能性のある専門用語、頭字語、その他の内部情報の使用は、ユーザー エクスペリエンスの向上を目的として使用しないようにします。また、画像、注釈付きのスクリーンショット、グラフィック、動画などの視覚的なコンテンツを使用して、システムの仕組みをユーザーに簡単に説明することも重要です。優れたドキュメントには、各セクションに何が表示されるかをユーザーに知らせるための見出しと副見出しの階層が必要です。また、その階層は、ユーザーがシステムを最も効果的に使用できるように学習するのに役立つ論理的な流れに沿っている必要があります。このプロジェクトの主な目的の一つは、ユーザー補助に対応したコンテンツを作成することです。すべてのドキュメントとガイドが一貫したスタイルに準拠します。複数のドキュメントで一貫したフォントと補完的な色を使用することは必須です。システムを成功させる方法に関する組織のリソースを、ユーザーがより多く利用できるようにします。
デベロッパー ガイド:
デベロッパー ガイドには、デベロッパーが DIPY のソースコードに貢献する際に役立つ詳細なガイダンスとリファレンス マテリアルが含まれています。利用可能なさまざまなオプションを整理して、達成したい目標に応じて適切なアプローチを使用できるようにします。開発ガイドの再構成と再編成が必要です。デベロッパー ガイドの内容を書き直します。依存関係の構築、コントリビューション ガイド、スタイルガイド、コーディング規約、ドキュメント ガイド、開発環境のインストール、デバッグ、テストガイド、関連する内容が含まれ、デベロッパーが簡単にアクセスできるようにします。新しいコントリビューターが初めてオープンソースに貢献するためにプロジェクトに急いで駆けつけるとき、彼らは貢献ガイドラインを頼りにします。したがって、ガイドラインは読みやすく、詳細で、親しみやすい内容になっています。貢献ガイドは、オープンソース プロジェクトに貢献する方法を説明する便利なドキュメントです。プロジェクトへの貢献は、修正の送信、バグの報告、メンテナーになる、コードの現在の状態に関するディスカッション、新機能の提案など、ユーザーにとって可能な限り簡単で透明なものにする必要があります。
テンプレート
これは、寄付ガイドに使用できるテンプレートの 1 つです。ドキュメントの要件に応じて、変更やセクションの追加、削除を行うことができます。
DIPY への貢献
- 歓迎メッセージ
目次
行動規範
- ポリシー
- 望ましい環境を築くうえで、次のような行動が期待されます。
- 参加者の許容されない行為の例
- Google の責任
- プロジェクト メンテナーの責任
- 範囲
行動規範の適用範囲
サポートするために知っておくべきことは何ですか？
コードのコントリビューションを支援したい場合は、このプロジェクトでは [プロジェクトで使用しているプログラミング言語、フレームワーク、ツールのリストを挿入] を使用します。まだコードを貢献する準備ができていない場合は、問題ありません。ドキュメントに関する問題 [Issue Tracker のドキュメントのラベルまたはタグへのリンク] や、デザインに関する問題 [プロジェクトでデザインの問題を追跡している場合は、Issue Tracker のデザインのラベルまたはタグへのリンク] を確認することもできます。コードの貢献に関心をお持ちで、Google が使用しているテクノロジーについて詳しく知りたい場合は、以下のリストをご覧ください。新しいコントリビューターがプロジェクトに貢献するために知っておくべきことを学ぶために使用できるリソース（チュートリアル、動画、書籍）の箇条書きリストを含めます。
開発環境のセットアップ
このセクションでは、インストール手順とインストールが必要な依存関係を追加します。install project を実行して $project をインストールします。
- ソースコード: github.com/$project/$project
- Issue Tracker: github.com/$project/$project/issues
ご協力いただくには
バグを報告する手順
- バグレポートを送信する前に
- バグを報告するにはどうすればよいですか？
変更を送信する方法
- pull リクエスト プロトコル
- チームからの回答
- レスポンスの速さ
機能強化をリクエストする方法
- 機能強化の提案を送信する前に
- 改善案を送信するにはどうすればよいですか？
最初のコードの貢献
- 初心者向けの問題
- 求人に関する問題 #### pull リクエスト
- pull リクエストの作成プロセス
- すべてのステータス チェックが合格していることを確認します。
ステータス チェックが失敗した場合はどうなりますか？
- テストの作成
- テストカバレッジ
スタイルガイド
- Git commit メッセージ
- 標準スタイル
サポート
問題が解決しない場合は、お気軽にお問い合わせください。サポートが必要な場合は、project@google-groups.com のメーリング リスト、IRC チャット、または [プロジェクトで使用しているその他のコミュニケーション プラットフォームをすべて列挙] で質問できます。
ライセンス
このセクションでは、プロジェクトのライセンスについて説明します。
時間の確保とコミュニケーション:
週に 45 時間以上勤務していますが、問題が起きた場合に備えて、その勤務時間は週末に補償します。コミュニティ ボンド期間中は、コミュニケーション手段について話し合い、メンターと毎週のミーティング、手段、時間を確定します。自分の仕事についてメンターに最新情報を提供します。仕事の詳細をメールでメンターに伝えます。画面共有などの機能が豊富で使いやすいため、TeamViewer をおすすめします。