このページには、Google シーズンのドキュメントで受け入れられているテクニカル ライティング プロジェクトの詳細が記載されています。
プロジェクトの概要
- オープンソースの組織:
- BRL-CAD
- テクニカル ライター:
- sahibkaur
- プロジェクト名:
- BRL-CAD の初心者向けガイド
- プロジェクトの期間:
- 標準の期間(3 か月)
プロジェクトの説明
BRL-CAD の初心者向けガイド
プロジェクトの概要
このプロジェクトは、BRL-CAD を初めて使用するユーザーだけでなく、オープンソースも初めて使用するユーザー専用のドキュメントを作成することを目的としています。
このプロジェクトの目的
BRL-CAD のウェブサイトを初めて訪れたときは、オープンソースと BRL-CAD を初めて使うので、一度にたくさんの情報に圧倒されました。しかし、深く考えれば、ここで学ぶことがたくさんあるとわかっていました。そのため、このコミュニティから多くを学び、安心して始められるように、私のような新規ユーザーのためにドキュメントを作成したいと考えました。
目標
このプロジェクトは新規ユーザーをターゲットにします。私のドキュメントで達成したい点を次にいくつか紹介します。 新規ユーザーに安心していただくため: このドキュメントは BRL-CAD を初めて利用するユーザーにとってだけでなく、オープンソースも初めて学ぶユーザーにとっても役立ちます。
以下の作業を行います。
- ドキュメントの Flesch-Kincaid スコアが 50 以上になっていることを確認してください。フレッシュ・キンケイド法によれば、スコアが高いほど、作品が理解しやすくなります。読みやすさスコアはオンラインで確認できます。
- 長い段落に飽きたり気を取られたりしないように、箇条書きや番号付きリストを使用します。
- 長い文を読んで理解するには比較的精神的な作業が必要になるため、段落や文を短くします。
- 小見出しを使用してテキストを分割します。 適切な構造のドキュメント: 適切な構造のドキュメントは、新規ユーザーをガイドするうえで重要な役割を果たします。子どもが道に迷うのを防ぎ、向かっている先や何をしているかを知らせることができます。 そのために、この初心者向けガイドを体系的に記録できる大まかなマインドマップを作成しました。
プロジェクトの説明
このプロジェクトでは、新規ユーザーがこのソフトウェアを実際に使い始められるようにドキュメントを作成することに重点を置いています。
以下は、ドキュメントをよりわかりやすくする例です。
基本概要: BRL-CAD(be-are-el-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 についての理解を深めることができるため、この部分ではさらに説明が必要になります。
- 主要ツールの基本的な使用方法: ここでは、主要ツールとその基本的な使用方法について個別のチュートリアルを用意します。順を追って説明するチュートリアルです。
- Export/Import: Geometry Conversion Library について説明します。BRL-CAD の最も一般的な用途は、ジオメトリをある形式から別の形式に変換することです。このセクションでは、エクスポート / インポート コンバータについて説明します。
- レンダリング: レンダリングの基本と、ソフトウェアでのレンダリングの必要性について説明します。また、BRL-CAD で画像をレンダリングする方法についても説明します。
それとは別に、以下の点にも焦点を当てます。
- ドキュメントの冒頭で、このソフトウェアが何についてのものなのかについて基本を理解できます。
- ユーザーがこのオープンソース コミュニティとつながる方法。BRL-CAD zulip チャットへのリンク。
- 抽象的には、ドキュメントを少しユーモアのあるものにして、新規ユーザーに大局的な言葉で落胆しないように求めることです。BRL-CAD Wiki のメインページに記載されている共感のアプローチが気に入りました。
- このソフトウェアを使用して実際にできることのスクリーンショットがいくつか表示されます。
マイルストーン
7 月(提案の審査期間)
- 既存のチュートリアルを見ながら、ソフトウェアとその Wiki ドキュメントにより理解を深めます。
- 既存のドキュメントを改善します。
8 月 1 日~ 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 日~ 22 日
- レンダリングのチュートリアル。
10 月 23 日~ 10 月 29 日
- すべてのドキュメントをレビューしています。
10 月 30 日~ 11 月 5 日
- ドキュメントブックの XML を操作する
11 月 6 日~ 11 月 12 日
- メンターや他のコミュニティ メンバーにレビューを依頼し、変更に取り組んでいます。
- メンターと話し合い、最終的な変更を加える。
11 月 12 日~ 11 月 22 日
- プロセスについての話し合いと変更。
- ドキュメントの最終仕上げを行う。
自己紹介
私は学校時代から書くことに夢中になっています。学校から帰ってきて、今日一日のことを書くことにします。今日一日を良くも悪くも書いたの。私はいつも、自分が犯した間違いと、それを改善するにはどうすればよいかを書き留めようとしていました。
ウェブ デザイナーとしての研修では、毎日学んだことを書き出すよう依頼されました。私が直面した問題と、その解決策を文書化します。
私は人間として、人の役に立つためにいつも全力を尽くしています。学校や大学時代には、自分で学んだトピックについて、友だちに説明したいと思っています。GSoD に参加することは、私が執筆者である私として、このオープンソース コミュニティを世界中の新しいユーザーにとってより魅力的で役に立つものにするために貢献できる素晴らしい一歩です。