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

From BRL-CAD
(stub three major documentation projects)
(Convert unmanaged docs to managed)
 
(19 intermediate revisions by the same user not shown)
Line 1: Line 1:
If you want to work on '''computer-aided design (CAD), geometry, or graphics''' documentation, you've come to the right place!  Help us improve open source CAD.
+
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. They are roughly in order or priority and difficulty.  Here are some links to help you get started with a proposal:
  
Well prepared proposals from capable technical writers have a good chance of getting selected. We consider proposals for all skill levels ranging from simple to crazy hard and everything in between. [https://brlcad.zulipchat.com Introduce yourself via chat], and we'll help you plan a project right for you.
+
# [https://brlcad.org/wiki/Compiling Get BRL-CAD source code]
 +
# [https://brlcad.org/wiki/Documentation Read our existing docs]
 +
# [https://brlcad.org/wiki/Main_page Get additional doc perspective]
 +
# [http://brlcad.org/HACKING_BRL-CAD.pdf Read our contributor guide]
  
Remember that project descriptions are just ''initial ideas''. You must expand with [[Summer_of_Code/Application_Guidelines|considerably more detail]].  Change the goals to fit your experience and interests.
+
We will consider GSoD proposals for '''all''' skill levels ranging from simple to crazy hard and everything in between. [https://brlcad.zulipchat.com Introduce yourself via chat] (preferred) or [mailto:devs@brlcad.org 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 [[Summer_of_Code/Application_Guidelines|considerably more detail]].  Set goals that fit your experience and interest.
 +
 +
<!--
 +
= Write an "Introduction to BRL-CAD" =
 +
 +
{|bgcolor=#fff
 +
!
 +
!align=center|Technologies
 +
!align=center|Difficulty
 +
!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 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:
 +
* see doc/docbook files in a Subversion checkout
 +
* http://brlcad.org/d/about
 +
* http://brlcad.org/HACKING_BRL-CAD.pdf
 +
|width=18% align=center bgcolor=#eee|Docbook XML
 +
|width=10% align=center|Easy
 +
|width=10% align=center bgcolor=#eee|morrison, rossberg
 +
|}
 +
-->
 +
 +
 +
= Upgrade doc infrastructure =
  
 
{| bgcolor=#fff
 
{| bgcolor=#fff
Line 12: Line 39:
 
!align=center|Contacts
 
!align=center|Contacts
 
|-
 
|-
|width=62%|'''Write an Introduction to BRL-CAD:'''  TBD.
+
|width=62%|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 [https://antora.org Antora] or [https://docusaurus.io Docusaurus] or [https://www.mkdocs.org MkDocs], converting everything over while still retaining build system integration.
|Docbook XML
+
References:
|align=center|Easy
+
* see doc/docbook in a source checkout
|align=center|morrison, rossberg
+
* http://brlcad.org/HACKING_BRL-CAD.pdf
 +
* https://docbook.org
 +
* https://antora.org
 +
|width=18% align=center bgcolor=#eee|Docbook XML, AsciiDoc, Markdown, Antora
 +
|width=10% align=center|Medium
 +
|width=10% align=center bgcolor=#eee|morrison, rossberg, yapp
 +
|}
 +
 
 +
= Organize all existing user docs =
 +
 
 +
{| bgcolor=#fff
 +
!
 +
!align=center|Technologies
 +
!align=center|Difficulty
 +
!align=center|Contacts
 
|-
 
|-
|width=62%|'''Organize all existing BRL-CAD documentation:''TBD.
+
|width=62%|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, catalog them, make recommendations and/or facilitate with merging overlapping documentation, and present all available documentation in a new web index.
|Mediawiki, Docbook XML, Subversion
+
References:
|align=center|Medium
+
* see doc/ hierarchy in a Subversion checkout
|align=center|morrison, rossberg
+
* http://brlcad.org/wiki/Documentation
 +
* http://brlcad.org/wiki/Main_Page
 +
* http://brlcad.org/HACKING_BRL-CAD.pdf
 +
 
 +
|width=18% align=center bgcolor=#eee|Mediawiki, Docbook XML, Subversion
 +
|width=10% align=center|Easy
 +
|width=10% align=center bgcolor=#eee|yapp, morrison, rossberg
 +
|}
 +
 
 +
= Write a "BRL-CAD Primitives" manual =
 +
 
 +
{| bgcolor=#fff
 +
!
 +
!align=center|Technologies
 +
!align=center|Difficulty
 +
!align=center|Contacts
 +
|-
 +
|width=62%|BRL-CAD has approximately 2 dozen primitives.  New users learning how to model with BRL-CAD for the first time end up utilizing an appendix 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:
 +
* see src/librt/primitives in a source checkout
 +
* http://brlcad.org/gallery/picture.php?/5/category/1
 +
* https://brlcad.org/w/images/c/cf/Introduction_to_MGED.pdf
 +
* http://brlcad.org/tmp/primitives/
 +
|width=18% align=center bgcolor=#eee|Docbook XML, Subversion, basic reading of C/C++
 +
|width=10% align=center|Hard
 +
|width=10% align=center bgcolor=#eee|morrison, rossberg
 +
|}
 +
 
 +
= Organize and publish developer docs =
 +
 
 +
{| bgcolor=#fff
 +
!
 +
!align=center|Technologies
 +
!align=center|Difficulty
 +
!align=center|Contacts
 +
|-
 +
|width=62%|BRL-CAD uses [http://www.doxygen.nl Doxygen] for API documentation.  It's a simple way for developers to document API by merely adding /** comments like this */ to their code, typically before a function.  The primary goal of this project is to make sure all of the public API has a Doxygen comment, has parameters tagged appropriately, grouped accordingly, and that all groupings are documented as well.  The secondary goal is to then publish the output from Doxygen to our website in HTML and PDF forms so that reference documentation is available to everyone.
 +
References:
 +
* see misc/doxygen in a source checkout
 +
* http://brlcad.org/HACKING_BRL-CAD.pdf
 +
* http://www.doxygen.nl
 +
|width=18% align=center bgcolor=#eee|Doxygen, Subversion, C/C++ code comments
 +
|width=10% align=center|Medium
 +
|width=10% align=center bgcolor=#eee|yapp, morrison, rossberg
 +
|}
 +
 
 +
 
 +
= Convert unmanaged to managed =
 +
 
 +
{| bgcolor=#fff
 +
!
 +
!align=center|Technologies
 +
!align=center|Difficulty
 +
!align=center|Contacts
 
|-
 
|-
|width=62%|'''Write a BRL-CAD Primitives manual:'''  TBD.  
+
|width=62%|BRL-CAD has several books, presentations, and other documentation written in familiar publishing tools like Microsoft Word, Microsoft Powerpoint, Adobe InDesign, LaTeX, Apple Pages, and more.  They are "unmanaged" in the sense that they are not easily kept in sync, unlike the majority of BRL-CAD's docs that are compiled alongside code and easily updated with a text editor (i.e., "managed").  The main reason they are unmanaged is because they have specific layout and formatting.  For this project, the goal is to figure out how to manage them so that they're in an editable markup format like AsciiDoc **and** any custom formatting is preserved (e.g., through the use of stylesheets).
|Docbook XML, Subversion, C/C++
+
References:
|align=center|Hard
+
* https://github.com/Ardemius/asciidoctor-presentation
|align=center|morrison, rossberg
+
* https://asciidoctor.org/docs/asciidoctor-revealjs/#convert-asciidoc-into-slides
 +
* http://rhythmus.be/md2indd/
 +
* https://pandoc.org
 +
|width=18% align=center bgcolor=#eee|AsciiDoc, Pandoc, Markdown, Docbook XML
 +
|width=10% align=center|Hard
 +
|width=10% align=center bgcolor=#eee|yapp, morrison, rossberg
 
|}
 
|}

Latest revision as of 11:32, 4 May 2020

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. They are roughly in order or priority and difficulty. 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.


Upgrade doc infrastructure[edit]

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 Antora or Docusaurus or MkDocs, converting everything over while still retaining build system integration.

References:

Docbook XML, AsciiDoc, Markdown, Antora Medium morrison, rossberg, yapp

Organize all existing user docs[edit]

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, catalog them, make recommendations and/or facilitate with merging overlapping documentation, and present all available documentation in a new web index.

References:

Mediawiki, Docbook XML, Subversion Easy yapp, morrison, rossberg

Write a "BRL-CAD Primitives" manual[edit]

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 an appendix 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, basic reading of C/C++ Hard morrison, rossberg

Organize and publish developer docs[edit]

Technologies Difficulty Contacts
BRL-CAD uses Doxygen for API documentation. It's a simple way for developers to document API by merely adding /** comments like this */ to their code, typically before a function. The primary goal of this project is to make sure all of the public API has a Doxygen comment, has parameters tagged appropriately, grouped accordingly, and that all groupings are documented as well. The secondary goal is to then publish the output from Doxygen to our website in HTML and PDF forms so that reference documentation is available to everyone.

References:

Doxygen, Subversion, C/C++ code comments Medium yapp, morrison, rossberg


Convert unmanaged to managed[edit]

Technologies Difficulty Contacts
BRL-CAD has several books, presentations, and other documentation written in familiar publishing tools like Microsoft Word, Microsoft Powerpoint, Adobe InDesign, LaTeX, Apple Pages, and more. They are "unmanaged" in the sense that they are not easily kept in sync, unlike the majority of BRL-CAD's docs that are compiled alongside code and easily updated with a text editor (i.e., "managed"). The main reason they are unmanaged is because they have specific layout and formatting. For this project, the goal is to figure out how to manage them so that they're in an editable markup format like AsciiDoc **and** any custom formatting is preserved (e.g., through the use of stylesheets).

References:

AsciiDoc, Pandoc, Markdown, Docbook XML Hard yapp, morrison, rossberg