CERN-HSF プロジェクト

このページには、Google シーズンのドキュメントで受け入れられているテクニカル ライティング プロジェクトの詳細が記載されています。

プロジェクトの概要

オープンソースの組織:
CERN-HSF
テクニカル ライター:
SabitaR
プロジェクト名:
Allpix Squared ドキュメントの再構築と合理化
プロジェクトの期間:
標準の期間（3 か月）

プロジェクトの説明

概要 CERN-HSF の Allpix Squared プロジェクトを選定しました。主な理由は 2 つあります。

  1. スキルの習得: このプロジェクトの既存のドキュメントは包括的であり、複数のコンテンツ形式が統合されています。この広範なドキュメント スイートを監査、再構築することで、情報アーキテクチャとライティング スキルを磨くことができます。 それに、プロジェクトのドメイン（素粒子物理学）は初めてのことです。開発者とのやり取りのスキルを磨くことが課題になっています。テクニカル ライターは、必要なバックグラウンド調査を行い、適切な質問をすれば、開発者からの情報を処理し、あらゆるレベルのユーザーに有用なコンテンツを提示できると思います。このプロジェクトでは、この理論をテストします。

  2. 技術的なノウハウ: このプロジェクトには Hugo が必要です。これは、自分が学習したいことのトップに載っているツールです。LaTeX-Markdown-Hugo-GitLab-CI のワークフローを学ぶのが楽しみです。

テクニカル ライターの探索フェーズで、プロジェクトのメンターと簡単にやり取りし、既存のドキュメント スイートの構造に精通しました。また、Windows マシンで Hugo と Docsy が正しく設定できるかどうかをテストするためのデモ用ウェブサイト（https://ap2-demo.netlify.app/）も作成しました。ウェブサイトを Netlify にはデプロイできましたが、GitLab Pages にはデプロイできませんでした。このプロジェクトでは、現在のデプロイ ワークフローを維持するために、Hugo Docsy テーマを GitLab ページにデプロイする方法を見つけます。

予想されるプロジェクト結果 - ドキュメント、コード リファレンス、チュートリアル、ニュースがまとめられた、合理化されたプロジェクト ウェブサイト。 - ユーザー マニュアルを再構成し、レビューしました。ユーザー マニュアルとデベロッパー向けコンテンツを分け、これまで不足していた情報が含まれています。 - ハウツー ドキュメント、よくある質問、よくある問題の実例に基づくチュートリアル ワークフロー。

プロジェクト ツール 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 をテストします - ボーナス: コミュニティでドキュメント作成のクイック リファレンス/ショートカット ドキュメントを作成します

  1. コンテンツの再構築、レビュー、強化（2020 年 9 月 14 日～ 10 月 19 日）: 週に 2 つのタスク、1 タスクあたり約 5 ～ 7 時間。このタイムラインには、予期せぬ遅延や問題に対処するための準備期間が含まれます。

    • ユーザー ワークフローを念頭に、既存のコンテンツとユーザーの分類を見直す
    • さまざまなユーザーのために再構成されたコンテンツ ワークフローの概要とテストを行う
    • 不足しているコンテンツを特定し、補強する
    • LaTeX ファイルをマークダウンに変換する
    • ユーザーガイドとデベロッパー ガイドの目次を完成させる
    • ユーザー ガイドやデベロッパー ガイドの PDF を生成
    • 参考: 例と問題からチュートリアルのコンテンツを構成する
    • 参考: ハウツー サンプルのチュートリアル ワークフローを設定する タイムライン: 5 週間（ドキュメント開発フェーズ）

  2. ウェブサイトを構築する（2020 年 10 月 19 日～ 11 月 30 日）: 週 1 ～ 2 個のタスク、1 タスクあたり約 5 ～ 7 時間。このタイムラインには、問題のトラブルシューティングと最終出力の微調整を行うためのバッファ週間が含まれます。

    • 公開ワークフローを理解してテストする
    • Hugo と Docsy を使用してウェブサイト構造を構築する
    • Docsy を使用して現在の自動デプロイとワークフローを維持する方法をテストする
    • Doxygen からコンテンツを pull する
    • LaTex や Markdown のコンテンツからユーザー マニュアル、デベロッパー ガイド、チュートリアルを作成できます
    • プロジェクトのウェブサイトの外観（ロゴ、色、テンプレート、レイアウト、リンク、ユーザビリティ、GitLab CI/CD）を完成させる。タイムライン: 6 週間（ドキュメントの作成フェーズ）