このページでは、Google Season of Docs に承認された技術文書作成プロジェクトの詳細について説明します。
プロジェクトの概要
- オープンソース組織:
- CERN-HSF
- テクニカル ライター:
- SabitaR
- プロジェクト名:
- Allpix Squared のドキュメントの再編成と合理化
- プロジェクト期間:
- 標準の期間（3 か月）
プロジェクトの説明
概要 CERN-HSF の Allpix Squared プロジェクトを選んだ理由は主に 2 つあります。
スキルの習得: このプロジェクトの既存のドキュメントは包括的で、複数のコンテンツ形式が統合されています。この広範なドキュメント スイートの監査と再構成は、情報アーキテクチャとライティング スキルの向上に役立ちます。それに、プロジェクトの分野（素粒子物理学）も初めてです。デベロッパーとのやり取りのスキルを磨くのが課題です。技術ライターは、必要な背景調査を行い、適切な質問をすることで、デベロッパーからの入力を処理し、あらゆるレベルのユーザーにとって有用なコンテンツを提供できると考えています。このプロジェクトでは、この理論をテストします。
技術的なノウハウ:このプロジェクトでは Hugo が必要です。これは、学習リストの上位にあるツールです。LaTeX-Markdown-Hugo-GitLab-CI のワークフローを学習するのを楽しみにしています。
技術ライター探索フェーズでは、プロジェクト メンターと簡単にやり取りし、既存のドキュメント スイートの構造を把握しました。また、Windows マシンで Hugo と Docsy を正しく構成できるかどうかをテストするために、デモ ウェブサイト（https://ap2-demo.netlify.app/）も作成しました。ウェブサイトは Netlify にデプロイできましたが、Gitlab Pages にはデプロイできませんでした。このプロジェクトで現在のデプロイ ワークフローを維持するため、Hugo Docsy テーマを Gitlab Pages にデプロイする方法を探します。
プロジェクトの期待される成果 - ドキュメント、コードリファレンス、チュートリアル、ニュースを統合した、合理化されたプロジェクト ウェブサイト。- ユーザーとデベロッパー向けのコンテンツを分離し、不足していた情報を追加した、再構成および改訂されたユーザー マニュアル。 - チュートリアル ワークフロー: 利用可能なチュートリアル、よくある質問、よくある問題の例から選択できます。
プロジェクト ツール Allpix Squared の現在のドキュメントでは、GitLab と GitLab CI に加えて、LaTeX、Doxygen、pandoc、Hugo が使用されています。プロジェクト メンターと私は、MathJax プラグインを使用してコンテンツを LaTeX から Markdown に移行する可能性について話し合いました。成功した場合、ドキュメント ワークフローには Hugo、Markdown、Doxygen、git、Gitlab CI が含まれます。 チュートリアルを同じウェブサイト/プラットフォーム内に維持するために、Hugo と Markdown を使用します。チュートリアルに Codelabs-as-a-Tool（ClaaT）を使用する可能性について教えてください。7 月に ClaaT-Hugo ワークフローをテストし、選ばれた場合はメンターと話し合いたいと思っています。
プロジェクトの期間 Allpix Squared プロジェクトを標準の 3 か月間（2020 年 9 月 14 日～ 2020 年 11 月 30 日）以内に完了することをリクエストします。この期間は、週に約 15 時間プロジェクトに費やします。この時間には、必要に応じてメンターとのミーティングや関連するメールも含まれます。コミュニティの結束とプロジェクトの完成に向けて、GSoD のタイムラインに沿って対応します。
プロジェクトのタスク 既存の Allpix Squared ドキュメント スイートへの提案された更新を実装する方法は次のとおりです。 1. オプションの調査、検討、検証（2020 年 8 月 17 日～ 9 月 13 日）: - プロジェクトの要件を理解します。 - Allpix Squared ソフトウェアをインストールして、現在のドキュメントに不足している情報（ある場合）を特定します。 - 必要な認証情報をリクエストします。 - Allpix Squared のさまざまなユーザー向けのユーザー ワークフローを作成します。 - ユーザーのロール別にコンテンツを分類します。 - LaTeX ファイルを Markdown に変換することの影響を確認します。 - ソース リポジトリを統合するか、複数の git リポジトリを操作する方法を理解します。 - ボーナス: チュートリアルのオプションとして CLaaT をテストします。 - ボーナス: コントリビューターがドキュメントを維持できるように、簡単なスタイルガイド/ショートコード リファレンスを作成します。 タイムライン: コミュニティの結束の段階
コンテンツの再編成、確認、拡充（2020 年 9 月 14 日～ 2020 年 10 月 19 日）: 週 2 件のタスク、タスクごとに約 5 ～ 7 時間。このタイムラインには、予期しない遅延や問題に対応するためのバッファ期間が含まれています。
- ユーザー ワークフローを念頭に、既存のコンテンツとユーザーの分類を確認する
- さまざまなユーザー向けに、再構成されたコンテンツのワークフローを概説してテストする
- 不足しているコンテンツを入手して補完する
- LaTeX ファイルを Markdown に変換する
- ユーザーガイドとデベロッパー ガイドの目次を完成させる
- ユーザー ガイドとデベロッパー ガイドの PDF を生成する
- ボーナス: 例と問題からチュートリアルのコンテンツを構造化する
- ボーナス: チュートリアル ワークフローを設定して、方法の例を作成します タイムライン: 5 週間（ドキュメント開発フェーズ）
ウェブサイトの構築（2020 年 10 月 19 日～ 11 月 30 日）: 週に 1 ～ 2 個のタスク、1 タスクあたり約 5 ～ 7 時間。このタイムラインには、問題のトラブルシューティングと最終的な出力の微調整のためのバッファ 1 週間が含まれています。
- 公開ワークフローを理解してテストする
- Hugo と Docsy を使用してウェブサイトの構造を構築する
- Docsy を使用して、現在の自動デプロイとワークフローを維持する方法をテストする
- Doxygen からコンテンツを pull する
- LaTex または Markdown のコンテンツからユーザー マニュアル、デベロッパー ガイド、チュートリアルを作成する
- プロジェクト ウェブサイトの外観（ロゴ、色、テンプレート、レイアウト、リンク、ユーザビリティ、Gitlab CI/CD）を確定します。 タイムライン: 6 週間（ドキュメント開発フェーズ）