このページには、Google シーズンの 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 は、オープンソース ライブラリのドキュメントを作成するためのよく知られたソリューションです。Python ドキュメント ツールである Sphinx をベースにしています。
長所:
- Ethereum（Solidity）などの組織によって使用される、広く受け入れられているドキュメント生成形式。
- 最適に構成されたドキュメント。
- 無料の静的ホスティング。
短所:
- スタイルを絶対的に制御できない。
= Sphinx の使用 Sphinx は、ドキュメントの部分でもネイティブで使用できます。Sphinx は、あらゆる目的に対して優れた機能を提供します。
長所:
- ドキュメント作成用の最も一般的な Python ツールです。
- ドキュメント検索もサポートしています。
- デフォルトの CSS は、カスタムの CSS でオーバーライドできます。.rst ファイルを使用して HTML を制御する要素もあります。
短所:
- Python でコーディングし、テキスト形式（.rst）を再構造化する必要がありますが、プロジェクトの候補言語とは異なります。
= Jekyll テーマの使用 Jekyll テーマは GitHub ページ内に統合されており、ニーズに応じてカスタマイズできる既存のテンプレートがあります。
長所:
- あらゆる用途に対応する既成のドキュメント テーマ。
- デフォルトの CSS とスタイルは、カスタムのものでオーバーライドされ、HTML でも制御できます。
- ページ作成用のデフォルトの Primer CSS を pull します。
- GitHub ページとの簡単な統合。
短所:
- 最適なドキュメント構成を提供できない可能性があります。
=GitHub ページの使用 静的サイト（HTML、CSS、JS）を構築するための標準的な GitHub ページです。
長所:
- 問題のほとんどすべてを完全に制御できます。
- レイアウト、色、スタイルを柔軟に決定できます。
- 語彙コンポーネントが使いやすい。
- コード スニペットとライブランのリンクを簡単に埋め込むことができます。
短所:
- より時間がかかる可能性があります。
= 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 ドキュメントのテーマを参考にして、同様のアイデアを得ることもできます。