Editing Google Season of Docs/Project Ideas
From BRL-CAD
Warning: You are not logged in. Your IP address will be publicly visible if you make any edits. If you log in or create an account, your edits will be attributed to your username, along with other benefits.
The edit can be undone.
Please check the comparison below to verify that this is what you want to do, and then save the changes below to finish undoing the edit.
Latest revision | Your text | ||
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! | + | 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 BRL-CAD. |
+ | Get started quickly: | ||
# [https://brlcad.org/wiki/Compiling Get BRL-CAD source code] | # [https://brlcad.org/wiki/Compiling Get BRL-CAD source code] | ||
# [https://brlcad.org/wiki/Documentation Read our existing docs] | # [https://brlcad.org/wiki/Documentation Read our existing docs] | ||
Line 6: | Line 7: | ||
# [http://brlcad.org/HACKING_BRL-CAD.pdf Read our contributor guide] | # [http://brlcad.org/HACKING_BRL-CAD.pdf Read our contributor guide] | ||
− | We | + | 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] (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]]. | + | Remember that project descriptions are just ''rough ideas''. You must expand with [[Summer_of_Code/Application_Guidelines|considerably more detail]]. Change the goals to fit your experience and interests. |
− | |||
− | |||
− | {|bgcolor=#fff | + | = Write an Introduction to BRL-CAD = |
+ | |||
+ | {| bgcolor=#fff | ||
! | ! | ||
!align=center|Technologies | !align=center|Technologies | ||
Line 19: | Line 20: | ||
!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 | + | |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. |
References: | References: | ||
* see doc/docbook files in a Subversion checkout | * see doc/docbook files in a Subversion checkout | ||
* http://brlcad.org/d/about | * http://brlcad.org/d/about | ||
* http://brlcad.org/HACKING_BRL-CAD.pdf | * http://brlcad.org/HACKING_BRL-CAD.pdf | ||
− | + | |Docbook XML | |
− | | | + | |align=center|Easy |
− | | | + | |align=center|morrison, rossberg |
|} | |} | ||
− | |||
− | |||
− | = | + | = Organize all existing BRL-CAD documentation = |
{| bgcolor=#fff | {| bgcolor=#fff | ||
Line 39: | Line 38: | ||
!align=center|Contacts | !align=center|Contacts | ||
|- | |- | ||
− | + | |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. 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 documentation in a new web index. | |
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |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 | ||
References: | References: | ||
* see doc/ hierarchy in a Subversion checkout | * see doc/ hierarchy in a Subversion checkout | ||
Line 65: | Line 45: | ||
* http://brlcad.org/HACKING_BRL-CAD.pdf | * http://brlcad.org/HACKING_BRL-CAD.pdf | ||
− | + | |Mediawiki, Docbook XML, Subversion | |
− | | | + | |align=center|Medium |
− | | | + | |align=center|morrison, rossberg |
|} | |} | ||
− | = Write a | + | = Write a BRL-CAD Primitives manual = |
{| bgcolor=#fff | {| bgcolor=#fff | ||
Line 78: | Line 58: | ||
!align=center|Contacts | !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 | + | |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 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: | References: | ||
* see src/librt/primitives in a source checkout | * see src/librt/primitives in a source checkout | ||
− | |||
* https://brlcad.org/w/images/c/cf/Introduction_to_MGED.pdf | * https://brlcad.org/w/images/c/cf/Introduction_to_MGED.pdf | ||
* http://brlcad.org/tmp/primitives/ | * http://brlcad.org/tmp/primitives/ | ||
− | + | |Docbook XML, Subversion, C/C++ | |
− | | | + | |align=center|Hard |
− | | | + | |align=center|morrison, rossberg |
|} | |} | ||
− | = | + | = Upgrade doc infrastructure = |
{| bgcolor=#fff | {| bgcolor=#fff | ||
Line 97: | Line 76: | ||
!align=center|Contacts | !align=center|Contacts | ||
|- | |- | ||
− | |width=62%|BRL-CAD | + | |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://docusaurus.io Docusaurus] or [https://antora.org Antora], converting everything over while still retaining build system integration. |
References: | References: | ||
− | * see | + | * see doc/docbook in a source checkout |
* http://brlcad.org/HACKING_BRL-CAD.pdf | * http://brlcad.org/HACKING_BRL-CAD.pdf | ||
− | + | * https://docbook.org | |
− | + | * https://docusaurus.io | |
− | + | |Docbook XML, Markdown, Subversion, Docusaurus | |
− | + | |align=center|Hard | |
− | + | |align=center|morrison, rossberg | |
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | * https:// | ||
− | |||
− | * https:// | ||
− | | | ||
− | | | ||
− | | | ||
|} | |} |