このページでは、Google Season of Docs に承認された技術文書作成プロジェクトの詳細について説明します。
プロジェクトの概要
- オープンソース組織:
- National Resource for Network Biology（NRNB）
- テクニカル ライター:
- Prubhtej_9
- プロジェクト名:
- SynBioHub のユーザー ドキュメントを作成し、特定のユースケースのチュートリアルを開発する
- プロジェクトの長さ:
- 標準期間（3 か月）
プロジェクトの説明
概要
ユーザー向けドキュメントは、エンドユーザーがプロダクトやサービスを使用できるように設計されています。優れたユーザー ドキュメントは非常に重要です。ユーザーがソフトウェアの使用方法、機能、ヒント、コツを学び、ソフトウェアの使用時に発生する一般的な問題を解決するための手段を提供できるためです。また、サポート費用を削減し、製品の企業アイデンティティの一部となります。つまり、優れたユーザー ドキュメントは、健全な製品とデベロッパー チームの証拠となります。優れたユーザー ドキュメントがないと、ユーザーは上記の作業を効果的かつ効率的に行う方法を把握できない可能性があります。ユーザー ドキュメントは、プロダクトを成功に導くうえで極めて重要な役割を果たします。優れたコミュニケーションは、あらゆるビジネスやプロダクトの中核をなすものであり、これからも常に存在し続けます。優れたドキュメントは、そのコミュニケーションを取りまとめ、誰もがアクセスできるように管理しやすいフレームワークにまとめます。SynBioHub は合成生物学の設計リポジトリです。公開ウェブサイトとしてもオープンソース ソフトウェアとしても入手できます。SynBioHub は、遺伝子設計を表現するためのオープンソース標準である Synthetic Biology Open Language（SBOL）を使用します。また、GenBank ファイルと FASTA ファイルの設計部品を共有することもできます。SynBioHub では、合成部品や設計のライブラリをサービスとして公開したり、設計を共同編集者と共有したり、生物システムの設計をローカルに保存したりできます。SynBioHub のデータには、HTTP API、Java API、Python API からアクセスできます。これらのデータは、CAD ツールに統合して遺伝子設計を構築できます。SynBioHub には、ユーザーが新しい生物データをデータベースにアップロードしたり、DNA 部品を可視化したり、クエリを実行して目的の部品にアクセスしたり、SBOL、GenBank、FASTA などをダウンロードしたりするためのインターフェースが含まれています。インターネット上には、次のようなさまざまな研究論文やチュートリアルも公開されています。1. https://pubs.acs.org/doi/abs/10.1021/acssynbio.7b00403 2. https://pubs.acs.org/doi/abs/10.1021/acssynbio.0c00056 SynBioHub には、API にのみ関連するドキュメントがいくつかありますが、GUI に関するドキュメントはありません。
ドキュメントの現在の状態:
現在、ユーザー向けのドキュメントは「https://synbiohub.github.io/api-docs/#about-synbiohub」で入手できます。これは API ドキュメントのみで、ユーザーが設計リポジトリ内を移動するのに役立つ GUI ドキュメントはありません。また、API ドキュメントも、ユーザーが直面する可能性のある特定の問題のトラブルシューティングなど、いくつかの特定のトピックについて更新する必要があります。組織は、こちらのようなチュートリアル動画をいくつか録画しています。SynBioHub に関するユーザー向けの書面によるドキュメントは、ユーザーをガイドするものはありません。
提案されたユーザー ドキュメントが現在のドキュメントよりも優れているのはなぜですか？メンターの Chris Myers 氏の提案に沿って、GitHub と Markdown を使用して GUI ドキュメントをゼロから作成します。提案されるユーザー ドキュメントは、エンドユーザーの効率性、一貫性、安心感を高め、確保するように構成されます。このドキュメントには、ガイドや関連画像のほか、オープンソース シミュレータの SynBioHub の各機能の使用方法や説明が含まれています。Myers 氏との話し合いの中で、API ドキュメントを GUI と統合し、6 つのセクション（6 つ目は省略可）にすることを決定しました。セクションは次のように記載されています。 1. イントロダクション 2. インストール手順 a）ビルド済みのイメージから b）ソースから c）NGINX 構成 3. ユーザー インストラクション a）各 GUI 機能の使用方法の詳細な手順 b）一般的なユースケースのチュートリアル 4. API ドキュメント - エンドポイント セクション 5。プラグインのドキュメント 6. トラブルシューティングと今後のリファレンス。
パート 1:
このセクションでは、SynBioHub について詳しく説明し、さまざまなチュートリアルを紹介します。
パート 2:
このセクションでは、ユーザーがさまざまな方法でオープンソース ソフトウェアをインストールするさまざまな方法について説明します。具体的には、以下の方法を使用します。 a）ビルド済みのイメージから b）ソースから c）NGINX 構成
パート 3:
これはドキュメントの中で最も重要な部分であり、ほとんどの時間を費やします。ここでは、GUI のコンテキストに細部まで追加されます。前述のように、このセクションでは主に 2 つの問題に対処します。つまり、各 GUI 機能の使用方法の詳細な手順と、一般的なユースケースのチュートリアルです。
パート 4:
前述のとおり、このパートのドキュメントの生成には Slate が使用されます。このセクションでは、次のエンドポイントについて説明します。ユーザー エンドポイント 2. エンドポイントを検索します。 エンドポイントのダウンロード 4. エンドポイント 5 をダウンロードします。送信エンドポイント 6. 権限エンドポイント。7. エンドポイントの編集 8. アタッチメント エンドポイント 9. 管理エンドポイント
パート 5:
このセクションでは、古い SynBioHub ドキュメントにすでに含まれているプラグインのドキュメントを紹介します。このセクションは、プラグインの仕様と実装の 2 つのセクションに分かれています。パート 6: [省略可] このセクションには、ユーザーが直面するよくあるエラーのリストとトラブルシューティング手順が含まれます。マイアーズ氏との話し合いの結果、このセクションは、長くなりすぎない限り、導入セクションと統合できることになりました。分析 Myers 氏と私は、既存のドキュメントを更新する方法と、GUI 用の新しいドキュメントを作成する方法について話し合いました。この数件の話し合いの中で、前述の新しいドキュメントの基本的なレイアウトを策定しました。推定スケジュールは、以下の 5 ページに記載されています。 議論に沿って、ドキュメントのパート 4 を除くすべてのセクションのドキュメントを作成するために、GitHub と Markdown を使用します。Slate:- Slate を使用すると、美しくインテリジェントで応答性の高い API ドキュメントを作成できます。Slate は Ruby ベースのツールで、一連のマークダウン ファイルから、見栄えの良い 3 ペインルの API ドキュメント静的サイトを生成します。旅行ソフトウェア会社「Tripit」の 18 歳のインターンだった 2013 年に開発者の Robert Lord が開発しました。彼はそのときに上司を説得してプロジェクトをオープンソース化し、それ以外は歴史に残っています。次の機能があります。• すっきりとした直感的なデザイン - Slate では、API の説明がドキュメントの左側に表示され、すべてのコード例が右側に表示されます。Stripe と PayPal の API ドキュメントを参考にしています。Slate はレスポンシブなので、タブレットやスマートフォンはもちろん、印刷物でも美しく表示されます。• すべてを 1 ページにまとめた - ユーザーは必要な情報を得るために何百万ものページを検索しなければならなかった時代は終わりました。Slate では、ドキュメント全体が 1 つのページに表示されます。リンク機能はそのまま残っています。スクロールすると、ブラウザのハッシュが最も近いヘッダーに更新されるため、ドキュメント内の特定の箇所にリンクすることは引き続き自然で簡単です。• Slate は単なるマークダウン - Slate でドキュメントを作成するときは、マークダウンを記述するだけです。編集や理解が簡単です。すべてが Markdown で記述されています。コードサンプルも Markdown のコードブロックです。• コードサンプルを複数の言語で作成する - API に複数のプログラミング言語のバインディングがある場合、タブに入れて言語間を簡単に切り替えることができます。ドキュメントでは、GitHub Flavored Markdown と同様に、各コードブロックの上部に言語名を指定して、言語を区別します。• 100 以上の言語ですぐに構文のハイライト表示が可能。構成は不要です。• ページの左端にある、自動でスムーズにスクロールする目次。スクロールすると、ドキュメント内の現在の位置が表示されます。高速で、TripIt では、新しい API のドキュメントを作成するために Slate を使用しています。このドキュメントの目次には 180 を超えるエントリがあります。Google では、ドキュメントのサイズが大きい場合でも、優れたパフォーマンスが維持されることを確認しています。• ユーザーがドキュメントを更新できるようにする - デフォルトでは、Slate で生成されたドキュメントは一般公開の GitHub リポジトリにホストされます。GitHub Pages を使用すると、ドキュメントを無料でホストできるだけでなく、他のデベロッパーがスペルミスなどの問題を見つけたときに、ドキュメントに対して pull リクエストを簡単に送信できます。もちろん、GitHub を使用したくない場合は、他の場所でドキュメントをホストすることもできます。• RTL サポート: アラビア語、ペルシャ語（Farsi）、ヘブライ語などの RTL 言語の完全な右から左のレイアウト。 結論: Slate はドキュメントの生成に最も強力なオープンソース ソフトウェアの 1 つです。メンターの Chris Myers 氏との話し合いに基づき、パート 4 では Slate を使用し、他のパートでは GitHub と Markdown を使用します。ドキュメントの詳細については、以降のセクションで説明します。提案されたドキュメントの構造 SynBioHub ユーザーガイドの構造を作成しました。2 ページ目をご覧ください。この構造は承認されており、すでに Myers 氏によって変更されています。プロジェクトの目標 1. ドキュメントを再編成します。2. SynBioHub の最新バージョンに合わせてドキュメントを更新しました。3. 古い情報を削除します。4. ユーザー ドキュメントを書き直してわかりやすくしました。5. 新しいコントリビューター向けのドキュメントに、前提条件の簡単なセクションを含めて、基本的な生物学的コンセプトと SynBioHub のインターフェースに関する基本的な理解を深めましょう。