このページには、Google シーズンのドキュメントで受け入れられているテクニカル ライティング プロジェクトの詳細が記載されています。
プロジェクトの概要
- オープンソースの組織:
- 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 などをダウンロードしたりするためのインターフェースが含まれています。インターネットには、次のようなさまざまな研究論文やドキュメントもいくつか存在します。
ドキュメントの現状:
現在、ユーザー ドキュメントは「https://synbiohub.github.io/api-docs/#about-synbiohub」で入手できます。これは API ドキュメントのみであり、ユーザーがデザイン リポジトリ内を移動する際に役立つ GUI ドキュメントは存在しません。 また、API ドキュメントについても、少し更新が必要です。特定のトピック（ユーザーが直面する可能性のある特定の問題のトラブルシューティングなど）も追加されています。組織では、ここに示すようなチュートリアル動画を録画しています。SynBioHub については、ユーザーに手助けできる書面によるユーザー ドキュメントはありません。
提案したユーザー ドキュメントが現在のドキュメントよりも改善された理由は何ですか。メンターの Chris Myers からすすめられたように、github とマークダウンを使用して 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:
これはドキュメントの最も重要な部分であり、ほとんどの時間を占めます。ここでは、1 分ごとの詳細が GUI のコンテキストとともに追加されます。前述のとおり、このセクションでは主に 2 つの懸念事項（各 GUI 機能の使用方法の詳細な手順と一般的なユースケースのチュートリアル）を取り上げます。
パート 4:
前述のとおり、このパートのドキュメントを作成するためにスレートが使用されます。このセクションでは、次のエンドポイントを含めます。 1. ユーザー エンドポイント 2. エンドポイントを検索します 3. エンドポイントをダウンロードします 4. エンドポイントをダウンロードします 5. 提出エンドポイント 6. 権限エンドポイント。7. エンドポイントを編集します 8. アタッチメント エンドポイント 9. 管理エンドポイント
パート 5:
このセクションでは、以前の SynBioHub のドキュメントにすでに存在しているプラグインのドキュメントについて説明します。このセクションは、プラグインの仕様と実装の 2 つのセクションに分かれています。パート 6: [省略可] このセクションでは、ユーザーが直面する一般的なエラーのリストと、トラブルシューティング手順について説明します。Mr Myers との話し合いの結果、あまりに長くならなければ、このセクションを概要セクションと統合しても構わないことが決まりました。 分析 Myers と私は、既存のドキュメントを更新する方法と、GUI 用の新しいドキュメントを作成する方法について話し合いました。これらの会話の中で、前述の新しいドキュメントの基本的なレイアウトを作成しました。下の 5 ページに、推定スケジュールが示されています。ディスカッションのとおり、スレートが使用されるドキュメントのパート 4 を除くすべてのセクションで、github とマークダウンを使用してドキュメントを作成します。Slate: 見栄えが良く、インテリジェントで応答性の高い API ドキュメントを作成できます。Slate は Ruby ベースのツールで、一連のマークダウン ファイルから、見栄えのよい 3 パネルの API ドキュメント静的サイトを生成します。この設計は、開発者の Robert Lord が 2013 年に旅行ソフトウェア会社「Tripit」で 18 歳のインターンだったときに作られました。当時、彼は上司にプロジェクトのオープンソース化を任せることを説得されました。それ以外は歴史です。 次のような特長があります。 • すっきりした直感的な設計 - Slate では API の説明がドキュメントの左側に、すべてのコードサンプルが右側に表示されます。Stripe と PayPal の API ドキュメントに基づいています。Slate は応答性が良いため、タブレット、スマートフォン、印刷物でも見栄えが良くなります。• すべてを 1 つのページに表示 - ユーザーが目的の情報を見つけるために何百万ものページを検索しなければならなかった時代は終わりました。スレートでは、ドキュメント全体が 1 つのページにまとめられています。しかし、Google はリンク可能性を犠牲にしていません。スクロールすると、ブラウザのハッシュが最も近いヘッダーに更新されるため、ドキュメント内の特定の箇所へのリンクは引き続き自然で簡単です。• スレートのマークダウン — Slate でドキュメントを作成するときにマークダウンを作成するだけで、簡単に編集、理解できます。すべて Markdown で記述され、コードサンプルであっても、単に Markdown コードブロックにすぎません。• コードサンプルを複数の言語で記述する - API に複数のプログラミング言語のバインディングがある場合、タブで簡単に切り替えられます。ドキュメントでは、GitHub Flavored Markdown と同様に、各コードブロックの先頭に言語名を指定してさまざまな言語を区別します。• 100 以上の言語ですぐに使用できる構文のハイライト表示機能。構成は不要です。• ページの左端に、自動的にスクロールする目次が表示されます。スクロールすると、ドキュメント内の現在の位置が表示されます。また、Google の AI は高速です。TripIt では、目次に 180 を超えるエントリがある新しい API のドキュメントを作成するために Slate を使用しています。大きなドキュメントでも優れたパフォーマンスを維持できるようにしています。• ユーザーによるドキュメントの更新 - デフォルトでは、S レートで生成されたドキュメントは公開 GitHub リポジトリにホストされています。これは、GitHub ページでドキュメントを無料ホストできるだけでなく、他のデベロッパーが入力ミスやその他問題に気づいた場合に、簡単にドキュメントに pull リクエストを発行できるようにします。もちろん、GitHub を使用したくない場合は、ドキュメントを別の場所でホストしてもかまいません。• RTL に対応。アラビア語、ペルシャ語（ファルシ語）、ヘブライ語などの RTL 言語を右から左に記述する完全なレイアウトに対応。 Verdict Slate はドキュメント生成に最適なオープンソース ソフトウェアの 1 つで、私のメンターである Chris Myers 氏との話し合いのとおり、パート 4 とそれ以外の部分には GitHub とマークダウンを使用します。ドキュメントの詳細については、以降のセクションで説明します。提案されたドキュメントの構造 SynBioHub ユーザーガイドの構造を作成しました。このドキュメントは 2 ページにあります。この構造は受け入れられ、すでに Myers 氏によって変更されています。プロジェクトの目標 1. ドキュメントの再構築。2. SynBioHub の最新バージョンに合わせてドキュメントを更新してください。3. 古い情報を削除する。4. ユーザー ドキュメントを書き換えて、理解しやすくします。5. 新しいコントリビューターのドキュメントに前提条件のセクションを簡単に追加して、基本的な生物学的概念と SynBioHub のインターフェースに関する基本的な理解を深められるようにします。