このページには、Google Season of Docs で承認されたテクニカル ライティング プロジェクトの詳細が掲載されています。
プロジェクトの概要
- オープンソース組織:
- BRL-CAD
- テクニカル ライター:
- sahibkaur
- プロジェクト名:
- BRL-CAD の初心者向けガイド
- プロジェクト期間:
- 標準期間(3 か月)
プロジェクトの説明
BRL-CAD の初心者向けガイド
プロジェクトの概要
このプロジェクトは、BRL-CAD だけでなくオープンソースも初めて使用するユーザー向けのドキュメントを作成することを目的としています。
このプロジェクトの目的
オープンソースと BRL-CAD は初めてだったので、BRL-CAD のウェブサイトに初めてアクセスしたとき、一度に表示される情報量の多さに圧倒されました。しかし、心の底では、ここで学ぶべきことがたくさんあることを知っていました。そこで、私のような新規ユーザーがこのコミュニティを最大限に活用し、安心して利用できるように、ドキュメントを作成することにしました。
目標
このプロジェクトは新規ユーザーを対象としています。そのため、このドキュメントでは次のような点を目標としています。 新規ユーザーが安心して使用できるようにする: このドキュメントは、BRL-CAD だけでなくオープンソースも初めて使用する新規ユーザーを対象としています。
そのために、私は次のことを行います。
- ドキュメントの Flesch-Kincaid スコアは 50 以上になるようにしてください。Flesch-Kincaid 法では、スコアが高いほど、文章が理解しやすくなります。読みやすさスコアはオンラインで確認できます。
- 長い段落で読者が飽きたり、気を散らしたりしないように、箇条書きや番号付きリストを使用します。
- 長い文を読んで理解するには、比較的精神的な働きが必要になるため、段落や文を短くします。
- テキストは小見出しを使って区切ります。 適切に構造化されたドキュメント: 適切に構造化されたドキュメントは、新規ユーザーを導くうえで重要な役割を果たします。ユーザーが道に迷うのを防ぎ、行き先と行動を知らせます。 そのために、この初心者向けガイドを整理して記述するのに役立つ、大まかなマインドマップを作成しました。
プロジェクトの説明
このプロジェクトでは、新しいユーザーがこのソフトウェアを使いこなせるようにするためのドキュメントの作成に重点を置いています。
以下に、ドキュメントをわかりやすくする方法の例を示します。
基本的な概要: BRL-CAD(読み方は「ビーアール キャド」)は、コンストラクティブ ソリッド ジオメトリ(CSG)ソリッド モデリングのコンピュータ支援設計(CAD)です。これは、3D コンピュータ支援設計とグラフィック可視化のための強力なクロスプラットフォームのオープンソースのソリッド モデリング システムです。理解できない場合は、詳しく見ていきましょう。オープンソース: オープンソース ソフトウェアは、誰でも検査、変更、拡張できるソースコードを持つソフトウェアです。BRL-CAD はオープンソース ソフトウェアです。皆様からの貢献を歓迎し、BRL-CAD をより良いものにしたいと考えています。コンピュータ支援設計(CAD): 簡単に言うと、CAD はコンピュータ プログラムを使用して物理的なオブジェクトの 2 次元または 3 次元のグラフィック表現を作成することです。ソリッド モデリング システム: BRL-CAD はソリッド モデリング CAD に重点を置いています。ソリッド モデリングは、物理的に正確で、3D 空間を完全に記述することに重点を置いている点で、他の形態のジオメトリ モデリングとは異なります。内部と外部の両方でオブジェクトをシミュレートします。コンストラクティブ ソリッド ジオメトリ(CSG): CSG を使用すると、複雑なモデルをプリミティブ間の一連のブール演算として表現できます。この表現に使用される最も単純なソリッド オブジェクトは、プリミティブと呼ばれます。 CSG の基礎的なレベルについては、こちらをご覧ください。
*プロジェクトのアイデアの説明で言及されているとおり: このドキュメントには、基本的なインストール、機能の全体的な説明、BRL-CAD のモデリングの原則、主要ツールの基本的な使用、モデリング、インポート/エクスポート、分析、レンダリングについて最低限記載されています。
ドキュメントの各部分について説明する内容の簡単な概要を記載しています。
- 基本的なインストール: BRL-CAD ソフトウェアをインストールする手順をチュートリアルとして追加し、必要なスクリーンショットも追加します。新規ユーザーは、まず新規ユーザー向けのチュートリアルをご覧ください。不足している機能の例:
- この初心者向けチュートリアルの手順には、箇条書きや番号は付けられていません。各ステップの最後にスクリーンショットを表示するチュートリアルを作成すると、ユーザーがチュートリアルに引き込まれやすくなります。
- 機能の全体的な説明: このセクションには、BRL-CAD が不思議を見せるあらゆる領域が含まれます。この部分に注目を集めるには、図表を使用する方法が適しています。
- BRL-CAD のモデリング原則: この部分は、これらのモデリング原則をしっかりと理解することで BRL-CAD をより深く理解できるため、より多くの説明が必要になります。
- 主なツールの基本的な使用方法: 主なツールとその基本的な使用方法については、個別のチュートリアルで説明します。順を追って説明したチュートリアルです。
- エクスポート/インポート: ユーザーはジオメトリ変換ライブラリについて学習します。BRL-CAD の最も一般的な用途の 1 つは、ジオメトリの形式を変換することです。このセクションでは、エクスポート コンバータとインポート コンバータについて説明します。
- レンダリング: レンダリングの基本と、ソフトウェアでの必要性について説明します。また、BRL-CAD で画像をレンダリングする方法についても学びます。
また、次の点にも重点を置いています。
- ドキュメントの冒頭では、このソフトウェアの概要について説明します。
- ユーザーがこのオープンソース コミュニティに接続する方法(BRL-CAD zulip チャットへのリンク)。
- 抽象的なレベルでは、ドキュメントを少しユーモラスにしたり、難しい言葉に惑わされないように新規ユーザーに伝えたりします。BRL-CAD ウィキのメインページで使用されている共感的なアプローチは良いと思いました。
- このソフトウェアを使用してユーザーができることに関する素晴らしいスクリーンショットが表示されます。
マイルストーン
7 月(提案書審査期間)
- 既存のチュートリアルを進めながら、ソフトウェアとその Wiki ドキュメントをよく理解するようにします。
- 既存のドキュメントを改善する予定です。
8 月 1 日~ 8 月 7 日(コミュニティの絆)
- プロジェクトについてメンターと話し合う。
- プロジェクトの詳細を調整する。
- 必要に応じて、マイルストーンに必要な変更を加えます。
8 月 8 日~ 8 月 14 日
- Docbook XML について学ぶ
8 月 15 日~ 8 月 21 日
- 「BRL-CAD の基本」のドキュメントの作成
- 「基本的なインストール」の詳細なチュートリアルの作成
8 月 22 日~ 8 月 27 日
- BRL-CAD のさまざまな機能を確認し、スクリーンショットとともに一覧表示します。
- 個々の機能については、別のページで説明します。
8 月 28 日~ 9 月 3 日
- 機能の個々のドキュメントの作業を継続します。
9 月 4 日~ 9 月 10 日
- モデリングの原則に関する作業。
- すべてのモデリング原則を説明します。
9 月 11 日~ 9 月 17 日
- 主要なツールの基本的な使用に取り組む
- アイデアのリストを作成して、各ツールの基本的な使用方法を記録します。
9 月 18 日~ 9 月 24 日
- 各ツールの使用状況を記録する。
9 月 25 日~ 10 月 1 日
- モデリングに取り組み、チュートリアル用のソリッド モデルを作成し、それとともに下書きを作成します。
10 月 2 日~ 10 月 8 日
- モデリングの下書きを改善しました。
10 月 2 日~ 10 月 8 日
- エクスポートとインポートのコンバータの調査。
10 月 9 日~ 10 月 15 日
- ドキュメントのエクスポートとインポートを準備します。
- レンダリング作業を開始します。
10 月 16 日~ 10 月 22 日
- レンダリング チュートリアルのドキュメント化。
10 月 23 日~ 10 月 29 日
- すべてのドキュメントを確認しています。
10 月 30 日~ 11 月 5 日
- Docbook XML の作業
11 月 6 日~ 11 月 12 日
- メンターや他のコミュニティ メンバーにレビューを依頼し、変更に取り組みます。
- メンターと話し合い、最終的な変更を加える。
11 月 12 日~ 11 月 22 日
- 議論と変更プロセス。
- ドキュメントの最終調整。
自己紹介
学生時代から文章を書くことに興味がありました。学校から帰宅したら、その日の出来事や、その日を良くした、または悪くした出来事についてすべて書き留めました。いつも、ミスした点と改善方法を書き留めていました。
ウェブ デザイナーのトレーニング中に、日々学んでいることを書き出すよう求められました。発生した問題とその解決策を記録します。
私は常に、他の人を助けるために最善を尽くしています。学校や大学時代、私はあるトピックを理解した後、そのトピックを友人に説明していました。GSoD に参加することは、ライターとして、このオープンソース コミュニティを世界中の新しいユーザーにとってより魅力的で有益なものにすることに貢献できる素晴らしいステップです。