Difference between revisions of "Google Season of Docs"

From BRL-CAD
(add gsod logo and link to doc management)
Line 2: Line 2:
 
BRL-CAD is excited to be applying to participate in the inaugural 2019 [https://developers.google.com/season-of-docs/ Google Season of Docs] (GSoD)!
 
BRL-CAD is excited to be applying to participate in the inaugural 2019 [https://developers.google.com/season-of-docs/ Google Season of Docs] (GSoD)!
  
 +
[[File:GSoD2019.png|frameless|120px|left]]
 
<blockquote style="background-color: lightgrey; border: solid thin grey;">The goal of [https://developers.google.com/season-of-docs/ Google Season of Docs] is to provide a framework for technical writers and open source projects to work together towards the common goal of improving an open source project's documentation. For technical writers who are new to open source, the program provides an opportunity to gain experience in contributing to open source projects. For technical writers who're already working in open source, the program provides a potentially new way of working together. Season of Docs also gives open source projects an opportunity to engage more of the technical writing community.</blockquote>
 
<blockquote style="background-color: lightgrey; border: solid thin grey;">The goal of [https://developers.google.com/season-of-docs/ Google Season of Docs] is to provide a framework for technical writers and open source projects to work together towards the common goal of improving an open source project's documentation. For technical writers who are new to open source, the program provides an opportunity to gain experience in contributing to open source projects. For technical writers who're already working in open source, the program provides a potentially new way of working together. Season of Docs also gives open source projects an opportunity to engage more of the technical writing community.</blockquote>
  
Line 8: Line 9:
 
BRL-CAD is a powerful cross-platform solid modeling system for 3D computer-aided design and graphic visualization. Currently standing at more than a million lines of code and hundreds of staff-years investment, BRL-CAD has nearly 40 years development history (since 1979) and is in production use by more than 2000 organizations around the world.  BRL-CAD is represented, used, and developed by a collective of industry, academia, and government participants from all over the world.
 
BRL-CAD is a powerful cross-platform solid modeling system for 3D computer-aided design and graphic visualization. Currently standing at more than a million lines of code and hundreds of staff-years investment, BRL-CAD has nearly 40 years development history (since 1979) and is in production use by more than 2000 organizations around the world.  BRL-CAD is represented, used, and developed by a collective of industry, academia, and government participants from all over the world.
  
In all, BRL-CAD has more than a million words of documentation across hundreds of manual pages, dozens of tutorials, hundreds of wiki pages, dozens of technical papers, and other resources. There are literally thousands of features created over decades of development.  BRL-CAD's set of current manuals, guides, tutorials, and other documentation [[Documentation|are listed]] on our [[Main_page|website wiki]].
+
In all, BRL-CAD has ''more than a '''million''' words'' of documentation across hundreds of manual pages, dozens of tutorials, hundreds of wiki pages, dozens of technical papers, and other resources. There are literally thousands of features created over decades of development.  BRL-CAD's set of current manuals, guides, tutorials, and other documentation [[Documentation|are listed]] on our [[Main_page|website wiki]].
  
 
= How You Can Help =
 
= How You Can Help =
Despite a rich documentation and development history ( see http://brlcad.org/BRL-CAD_Bibliography.pdf ), BRL-CAD's docs are lacking in several fundamental respects such as introductory materials for new users, basic organization, and presentation. The project has received very little attention from professional technical writers in the past 20 years.
+
The project has received little attention from professional technical writers in the past 15 years.  Despite a rich documentation and development history ( see http://brlcad.org/BRL-CAD_Bibliography.pdf ), BRL-CAD's docs are lacking in several fundamental respects such as introductory materials for new users, basic organization, and presentation.
 +
 
 +
We especially need help with:
  
There remain large gaps particularly for new users.  We especially need help with:
 
 
* creating documentation that specifically caters to new users
 
* creating documentation that specifically caters to new users
 
* presenting BRL-CAD's existing documentation in a more organized manner
 
* presenting BRL-CAD's existing documentation in a more organized manner
 
* getting all existing documentation under version control so we can manage better
 
* getting all existing documentation under version control so we can manage better
 
* setting up round-trip editing of documentation so we can update and maintain faster
 
* setting up round-trip editing of documentation so we can update and maintain faster
 +
* converting our doc management from Docbook XML to [https://docusaurus.io Docusaurus] or [https://antora.org Antora]
  
 
= [https://brlcad.org/w/index.php?title=Google_Season_of_Docs/Project_Ideas PROJECT IDEAS] =
 
= [https://brlcad.org/w/index.php?title=Google_Season_of_Docs/Project_Ideas PROJECT IDEAS] =
  
 
If you are interested in working with BRL-CAD on a documentation project, whether under GSoD or not, please see our [https://brlcad.org/w/index.php?title=Google_Season_of_Docs/Project_Ideas project ideas page].  Another good starting point for technical writers is our "HACKING BRL-CAD" book which can be accessed at http://brlcad.org/HACKING_BRL-CAD.pdf  (35MB)
 
If you are interested in working with BRL-CAD on a documentation project, whether under GSoD or not, please see our [https://brlcad.org/w/index.php?title=Google_Season_of_Docs/Project_Ideas project ideas page].  Another good starting point for technical writers is our "HACKING BRL-CAD" book which can be accessed at http://brlcad.org/HACKING_BRL-CAD.pdf  (35MB)

Revision as of 14:21, 22 April 2019

About GSoD

BRL-CAD is excited to be applying to participate in the inaugural 2019 Google Season of Docs (GSoD)!

Error creating thumbnail: File missing

The goal of Google Season of Docs is to provide a framework for technical writers and open source projects to work together towards the common goal of improving an open source project's documentation. For technical writers who are new to open source, the program provides an opportunity to gain experience in contributing to open source projects. For technical writers who're already working in open source, the program provides a potentially new way of working together. Season of Docs also gives open source projects an opportunity to engage more of the technical writing community.

Immense Legacy

BRL-CAD is a powerful cross-platform solid modeling system for 3D computer-aided design and graphic visualization. Currently standing at more than a million lines of code and hundreds of staff-years investment, BRL-CAD has nearly 40 years development history (since 1979) and is in production use by more than 2000 organizations around the world. BRL-CAD is represented, used, and developed by a collective of industry, academia, and government participants from all over the world.

In all, BRL-CAD has more than a million words of documentation across hundreds of manual pages, dozens of tutorials, hundreds of wiki pages, dozens of technical papers, and other resources. There are literally thousands of features created over decades of development. BRL-CAD's set of current manuals, guides, tutorials, and other documentation are listed on our website wiki.

How You Can Help

The project has received little attention from professional technical writers in the past 15 years. Despite a rich documentation and development history ( see http://brlcad.org/BRL-CAD_Bibliography.pdf ), BRL-CAD's docs are lacking in several fundamental respects such as introductory materials for new users, basic organization, and presentation.

We especially need help with:

  • creating documentation that specifically caters to new users
  • presenting BRL-CAD's existing documentation in a more organized manner
  • getting all existing documentation under version control so we can manage better
  • setting up round-trip editing of documentation so we can update and maintain faster
  • converting our doc management from Docbook XML to Docusaurus or Antora

PROJECT IDEAS

If you are interested in working with BRL-CAD on a documentation project, whether under GSoD or not, please see our project ideas page. Another good starting point for technical writers is our "HACKING BRL-CAD" book which can be accessed at http://brlcad.org/HACKING_BRL-CAD.pdf (35MB)