Difference between revisions of "Google Season of Docs/Project Ideas"

From BRL-CAD
(Organize all existing BRL-CAD documentation)
(Write an Introduction to BRL-CAD)
Line 19: Line 19:
 
!align=center|Contacts
 
!align=center|Contacts
 
|-
 
|-
|width=62%|This is as straight-forward as it sounds, write an introduction intended for users discovering BRL-CAD for the first time.  It should minimally cover installation, an overall description of capabilities, of the runtime philosophy, basic usage of major tools, modeling, and rendering.
+
|width=62%|This is as straight-forward as it sounds, write an introduction intended for users discovering BRL-CAD for the first time.  It should minimally cover basic installation, an overall description of capabilities, of BRL-CAD's modeling principles, basic usage of major tools, modeling, import/export, analysis, and rendering.  It should be as concise as possible, structured either as a single independent document or series of independent articles.
 
References:
 
References:
 
* see doc/docbook files in a Subversion checkout
 
* see doc/docbook files in a Subversion checkout

Revision as of 15:49, 22 April 2019

If you want to work on computer-aided design (CAD), geometry, or graphics documentation, you've come to the right place! Please check out our project ideas below. Here are some links to help you get started with a proposal:

  1. Get BRL-CAD source code
  2. Read our existing docs
  3. Get additional doc perspective
  4. Read our contributor guide

We will consider GSoD proposals for all skill levels ranging from simple to crazy hard and everything in between. Introduce yourself via chat (preferred) or via e-mail, and we'll help you plan a project right for you.

Remember that project descriptions are just rough ideas. You must expand with considerably more detail. Set goals that fit your experience and interest.


Write an Introduction to BRL-CAD

Technologies Difficulty Contacts
This is as straight-forward as it sounds, write an introduction intended for users discovering BRL-CAD for the first time. It should minimally cover basic installation, an overall description of capabilities, of BRL-CAD's modeling principles, basic usage of major tools, modeling, import/export, analysis, and rendering. It should be as concise as possible, structured either as a single independent document or series of independent articles.

References:

Docbook XML Easy morrison, rossberg

Organize all existing BRL-CAD documentation

Technologies Difficulty Contacts
Tame the beast. BRL-CAD has more than a million words of documentation spread across hundreds of documents. Some are huge, some are small. There are books, articles, presentations, manual pages, diagrams, reference cards, and more in a variety of formats and locations. The goal of this task to to conduct a complete audit of all existing documentation, categorize and organize documentation, make recommendations and/or facilitate with merging overlapping documentation, and present all available documentation in a new web index.

References:

Mediawiki, Docbook XML, Subversion Medium morrison, rossberg

Write a BRL-CAD Primitives manual

Technologies Difficulty Contacts
BRL-CAD has approximately 2 dozen primitives. New users learning how to model with BRL-CAD for the first time end up utilizing Appendix A in our existing MGED Tutorial Series, which is a brief guide to some of the supported primitives. For this project, we'd like all primitives to be documented with rendered visuals where appropriate, explanation of all parameters, and depiction of the variety possible with each primitive.

References:

Docbook XML, Subversion, C/C++ Hard morrison, rossberg

Upgrade doc infrastructure

Technologies Difficulty Contacts
BRL-CAD has extensive documentation infrastructure using Docbook XML whereby we "compile" them into HTML, PDF, and other formats. This approach helps ensure docs remain up-to-date, without syntax/structure errors, and allows the documentation to be composed and reused in different ways (e.g., an tutorial on some topic might get embedded as an appendix in one document or a chapter to another). That said, the underlying format is tedious to write and hard for contributors. We'd like to migrate to a newer system like Docusaurus or Antora, converting everything over while still retaining build system integration.

References:

Docbook XML, Markdown, Subversion, Docusaurus Hard morrison, rossberg