このページには、Google シーズンのドキュメントで受け入れられているテクニカル ライティング プロジェクトの詳細が記載されています。
プロジェクトの概要
- オープンソースの組織:
- クリエイティブ・コモンズ
- テクニカル ライター:
- nimishnb
- プロジェクト名:
- 用語集の使用方法ガイド
- プロジェクトの期間:
- 標準の期間（3 か月）
プロジェクトの説明
プロジェクトの概要
語彙は、ウェブサイト構築の主要な UI コンポーネント ライブラリとして使用される可能性が非常に高いです。堅牢でありながらもわかりやすいハウツー ガイドが必要です。ドキュメントには、コンポーネント ガイド、使用仕様、構成の微調整などの重要なデベロッパー情報が欠かせません。これにより、既存のユーザーが語彙がどのように増え続けているかを把握し、新たなマイルストーンに到達するだけでなく、比較的新しいプロジェクトにおける語彙の利用を促進できます。インターンとしての私のスピントから望ましい成果には、既存のコンポーネントを使用するためのシンプルなガイドを作成するだけでなく、Vocabulary、Vue-Vocabulary、Fonts のホームページ（それぞれの統合ドキュメントにつながる）を設計、開発することも含まれます。
プロジェクトの計画
問題: ドキュメントは、特定のオープンソース ライブラリがどれほど成功するかを決定する主な理由の一つです。デベロッパーがアプリケーション構築に適した技術スタックを選択する際に考える主な質問は、「ライブラリは適切に文書化されているか？メンテナンスは万全ですか？かなりの使用法やエラー サポートになっていますか？」といった質問です。これが、このプロジェクトのアイデアに取り組む際に自問すべき問いです。ソフトウェア エンジニアリングの観点から:
要件の分析: 私たちのニーズに合った、簡潔かつ統合的なドキュメントが切実に求められています。ドキュメントが欠けていることは、オープンソース アプリケーションの将来的な見通しを損なうものであり、間違いなく不可欠な要素であり、無視できないものです。これらのドキュメントへのリンクは、ユーザーの関心を即座に引きつける魅力的なホームページである必要があります。ドキュメントは、円滑に進められるように、よく整理する必要があります。
仕様: 要件に応じて、仕様を決定できます。ドキュメントの内容は、CC Netlify ウェブサイトのデータのほか、semantic-ui、scikit-learn、numpy、bootstrap などのよく知られたドキュメントからインスピレーションを得ることができます。このタスクの出力は、必須のランディング ページと完全なドキュメント ガイドになります。
Vocabulary、Vue-Vocabulary、Fonts に関する一般的な問題には、現在のところ次のようなものがあります。
ドキュメントはなく、いくつかあってもその一部が netlify のウェブサイト全体に散らばっています。これによって、ユーザー、デベロッパー、外部のコントリビューターが Google のライブラリを利用できなくなるわけではありません。
特定のコンポーネントにアクセスして対応するコードをコピーするには、さらにクリックする必要があります。 「タブ コンポーネント CC 用語」のような単純な Google 検索では、目的の情報が返されません。ドキュメント ガイド内の検索オプションを使用すると、UX が大幅に向上します。
もう少しテキストによるコンポーネントの説明で、わかりにくい詳細について説明します。
ライブ実行オプションはありません。ライブ実行は JSFiddle などのさまざまなサイトでサポートされており、デベロッパーはアプリケーション全体を実行しなくてもコンポーネントの動作を確認できます。
ソリューション
解決策は複数あります。ただし、ここでいくつか触れて、最終的な解決策を提示します。
= readthedocs を使用すること。readthedocs はオープンソース ライブラリのドキュメントを作成するためのよく知られたソリューションです。Python ドキュメント ツールである Sphinx をベースにしています。
長所:
- Ethereum（Solidity）などの組織で使用される、広く受け入れられているドキュメント生成の形式。
- 最適に構造化されたドキュメント。
- 無料の静的ホスティング。
短所:
- スタイルを完全に制御できない。
= Sphinx を使用する Sphinx はドキュメント部分でもネイティブで使用できます。Sphinx はあらゆる目的に適切な機能を提供します。
長所:
- ドキュメント作成用の最も一般的な Python ツール。
- ドキュメント検索もサポートされています。
- デフォルトの CSS はカスタムでオーバーライドでき、.rst ファイルを使用して HTML を制御することもあります。
短所:
- Python でコーディングし、テキスト形式（.rst）を再構成する必要が、提案されているプロジェクト言語から逸脱している。
= Jekyll のテーマを使用する Jekyll のテーマは GitHub ページ内に統合されており、ニーズに応じてカスタマイズできる既存のテンプレートがあります。
長所:
- あらゆる目的に合わせて用意されたドキュメントのテーマ。
- デフォルトの CSS とスタイルは、カスタムの要素でオーバーライドでき、HTML でも制御できます。
- ページの作成に使用するデフォルトの Primer CSS を pull します。
- GitHub ページとの簡単な統合。
短所:
- ドキュメント構成が適切でない場合があります。
=GitHub ページの使用 静的サイトを構築するための標準の GitHub ページ（HTML、CSS、JS）。
長所:
- 問題のほとんどすべてに対する完全な制御権限。
- レイアウト、色、スタイルを柔軟に決定できます。
- Vocabulary コンポーネントを簡単に使用できる。
- コード スニペットとライブ実行リンクを簡単に埋め込める。
短所:
- これはより時間がかかる可能性があります。
= Haroopad を使用します これは代替のマークダウン ソリューションです。
長所:
- 最小限の手間でコーディングできます。
- ドキュメントを完璧に作成することに注力します。
短所:
- CSS を制御できない。
- コミュニティ サポートが最適である場合も、そうでない場合もあります。
- MDX はサポートされていない場合があります。
= MKDocs を使用する これは、別の代替マークダウン ソリューションを提供します。
長所:
- 繰り返しになりますが、最小限の手間でコーディングする必要があります。
- より多く書く、コーディング時間を減らすアプローチ。
短所:
- CSS を制御できない。
- 最適なコミュニティ サポートを利用できない場合があります。
- Python を使用します。Amazon S3 インスタンスのスピンアップが必要になる可能性もあります。
= VueJS +StorybookJS を使用する このアプローチは、Vocabulary とその姉妹リポジトリで広く使用されています。
長所:
- 過去の実務経験を考慮し、問題なく動作することが保証されているテクノロジーを使用し続ける。
- コードベースに精通していること。
- この分野では優れたテクノロジーはありません。
短所:
- 同じ目的で、よりシンプルなオプションも使用できます。
私自身も VueJS + Storybook を使ったアプローチ（HTML、CSS、JS）を取り入れるのが適しているように思います。しかし、このことは、このアプリケーションの開発にまったく踏み込むことがないことも意味します。CC-Vocabulary コンポーネントを使用するのも非常に簡単です。ただし、ドキュメントの構造を決めるにあたっては、readthedocs のドキュメントで内容が小見出しの間でどのように分割されているかを必ず考慮する必要があります。Semantic-UI ウェブサイト（StoryBook を使用）はシンプルなデザインで、数回クリックするだけで必要なものを簡単に理解できるという点に感銘を受けました。Semantic-UI とは別に、マテリアル デザイン、Primer、Bootstrap、Carbon Design なども検討し、自分の UI スタイル設定のガイドやデザイン システムとして使用しました。また、既製の Jekyll ドキュメントのテーマを調べて、同様のアイデアを得ることもできます。