このページには、Google Season of Docs で承認されたテクニカル ライティング プロジェクトの詳細が掲載されています。
プロジェクトの概要
- オープンソースの組織:
- クリエイティブ・コモンズ
- テクニカル ライター:
- nimishnb
- プロジェクト名:
- 語彙の使用ガイド
- プロジェクト期間:
- 標準の期間（3 か月）
プロジェクトの説明
プロジェクトの概要
Vocabulary は、ウェブサイト構築用の主な UI コンポーネント ライブラリとして使用できる大きな可能性を秘めています。必要なのは、堅牢でありながら誰でも理解しやすいハウツーガイドです。コンポーネント ガイド、使用仕様、構成の調整などの重要なデベロッパー情報は、どのドキュメントにも不可欠な部分です。これにより、既存のユーザーは、ボキャブラリーが継続的に成長し、新しいマイルストーンに到達する様子を確認できるだけでなく、比較的新しいプロジェクトでボキャブラリーの使用を促進できます。インターンとしての私が求める成果は、既存のコンポーネントの使用に関するシンプルなガイドを作成するだけでなく、語彙、Vue-Vocabulary、Fonts のホームページをデザインし開発すること（それぞれが統合されるドキュメントにつながる）にもなるでしょう。
プロジェクト計画
問題: ドキュメントは、特定のオープンソース ライブラリの成功を左右する主な要因の一つです。アプリケーションを構築するための適切な技術スタックを選択する際に、デベロッパーが考える主な質問は、「ライブラリは十分にドキュメント化されているか？」です。メンテナンスは行き届いていますか？使用状況やエラーのサポートは十分か？」といった質問です。これらの質問は、プロジェクトのアイデアを検討する際に自問すべき内容です。ソフトウェア エンジニアリングの観点から:
要件分析: ニーズに関する簡潔で統合されたドキュメントを作成することが不可欠です。ドキュメントが不足していると、オープンソース アプリケーションの将来性が損なわれます。ドキュメントは、オープンソース アプリケーションにとって不可欠で、軽視できないコンポーネントです。これらのドキュメントへのリンクは、ユーザーの興味をすぐに引き付ける魅力的なホームページにする必要があります。ドキュメントは適切に整理し、シームレスな流れを実現する必要があります。
仕様: 要件に応じて、仕様を決定できます。ドキュメントの内容は、CC netlify ウェブサイトにあるデータから作成できます。また、semantic-ui、scikit-learn、numpy、bootstrap などのよく知られたドキュメントからヒントを得ることもできます。このタスクの出力は、必要なランディング ページと完全なドキュメント ガイドです。
現在、Vocabulary、Vue-Vocabulary、Fonts に関連する一般的な問題は次のとおりです。
ドキュメントはなく、いくらかあったとしても、その一部は netlify のウェブサイトに散在しています。ただし、ユーザー、デベロッパー、外部コントリビューターがライブラリを使用できるわけではありません。
特定のコンポーネントにアクセスして、対応するコードをコピーするには、さらにクリックする必要があります。「タブ コンポーネントの CC 用語」などのキーワードで Google 検索しても、目的の情報は返されません。ドキュメント ガイド内に検索オプションがあると、UX が大幅に改善されます。
コンポーネントの詳細な説明。わかりにくい詳細を説明します。
ライブランのオプションはありません。ライブランは JSFiddle などのさまざまなサイトでサポートされており、デベロッパーはアプリケーション全体を実行して機能を確認することなく、コンポーネントの動作を確認できます。
ソリューション
考えられる解決策は複数あります。ここではいくつかに触れ、まとめの部分で最終的な解決策を紹介します。
readthedocs の使用 readthedocs は、オープンソース ライブラリのドキュメントを作成するためのソリューションとしてよく知られています。Python のドキュメント ツールである Sphinx をベースにしています。
長所:
- 広く受け入れられているドキュメント生成形式で、Ethereum（Solidity）などの組織で使用されています。
- 最適な構造のドキュメント。
- 無料の静的ホスティング。
短所:
- スタイルを完全に制御できない。
= Sphinx の使用 ドキュメント部分にも Sphinx をネイティブに使用できます。Sphinx には、すべての目的に適した優れた機能が用意されています。
長所:
- ドキュメント作成に最もよく使用される Python ツール。
- ドキュメントの検索もサポートされています。
- デフォルトの CSS はカスタム CSS でオーバーライドできます。.rst ファイルを使用して HTML をある程度制御できます。
短所:
- Python とリストラクチャリングされたテキスト形式（.rst）でのコード作成が必要になるため、推奨されるプロジェクト言語から逸脱します。
= Jekyll テーマを使用する Jekyll テーマは GitHub ページに統合されており、ニーズに応じてカスタマイズできる既存のテンプレートがあります。
長所:
- あらゆる目的に使用できるドキュメント テーマがあらかじめ用意されています。
- デフォルトの CSS とスタイルは、カスタム CSS とスタイルでオーバーライドできます。HTML も制御できます。
- ページの作成に必要なデフォルトの Primer CSS を取得します。
- GitHub ページと簡単に統合できます。
短所:
- 最適なドキュメント構造が提供されない場合があります。
=GitHub ページを使用する 静的サイト（HTML、CSS、JS）を構築するための標準の GitHub ページ。
長所:
- 対象となるほぼすべてのものを完全に制御できます。
- レイアウト、色、スタイルを柔軟に決定できます。
- 語彙コンポーネントを簡単に使用できる。
- コード スニペットとライブ実行リンクを簡単に埋め込むことができます。
短所:
- 時間のかかるアプローチになる可能性があります。
= Haroopad の使用 これは、代わりに別のマークダウン ソリューションを提供します。
長所:
- 扱いにくいコーディングが最小限に抑えられます。
- ドキュメントの完璧な作成に重点を置きます。
短所:
- CSS を制御できない。
- コミュニティ サポートが最適である場合も、そうでない場合もあります。
- MDX をサポートしていない場合があります。
= MKDocs を使用する 代わりに、別のマークダウン ソリューションを使用できます。
長所:
- 最低限の扱いにくいコーディングが必要になります。
- 記述量を減らしてコード量を増やすアプローチ。
短所:
- CSS を制御できない。
- コミュニティ サポートが十分でない可能性があります。
- Python を使用します。さらに、Amazon S3 インスタンスを起動する必要がある場合があります。
= VueJS +StorybookJS の使用 このアプローチは、語彙とその姉妹リポジトリでよく使用されます。
長所:
- 過去の職務経験から、問題なく動作することが保証されているテクノロジーに固執する。
- コードベースに精通していること。
- この分野で適切な技術がない。
短所:
- 同じ目的でよりシンプルなオプションが用意されていることもあります。
結論として、VueJS+Storybook アプローチ（HTML、CSS、JS）が最も適していると思われます。私自身もこの方法に慣れているためです。ただし、このアプリケーションの開発に際して、Google が特別な努力を払う必要はありません。CC-Vocabulary コンポーネントを使用するのも簡単です。ただし、ドキュメントの構造を決定するには、readthedocs ドキュメントでコンテンツがサブヘッダーに分割されている方法を必ず考慮する必要があります。Semantic-UI のウェブサイト（StoryBook を使用）は、ミニマルな外観で、数回クリックするだけで必要な情報を簡単に把握できる点が印象的でした。Semantic-UI 以外にも、マテリアル デザイン、Primer、Bootstrap、Carbon Design など、UI スタイルガイドやデザイン システムとして使用できるものを調べました。既製の Jekyll ドキュメント テーマを調べて、アイデアを得ることもできます。