Editing Google Season of Docs/Proposal
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: | ||
| + | This is our 2021 organization proposal to the Google Season of Docs. Please direct any questions or comments to devs@brlcad.org | ||
= Migrate BRL-CAD's Documentation Infrastructure = | = Migrate BRL-CAD's Documentation Infrastructure = | ||
| − | |||
| − | |||
== About BRL-CAD == | == About BRL-CAD == | ||
| Line 19: | Line 18: | ||
|- | |- | ||
|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. | |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. | ||
| − | |||
References: | References: | ||
* see doc/docbook in a source checkout | * see doc/docbook in a source checkout | ||
| Line 27: | Line 25: | ||
|width=18% align=center bgcolor=#eee|Docbook XML, AsciiDoc, Markdown, Antora | |width=18% align=center bgcolor=#eee|Docbook XML, AsciiDoc, Markdown, Antora | ||
|width=10% align=center|Medium | |width=10% align=center|Medium | ||
| − | |width=10% align=center bgcolor=#eee|morrison, rossberg, yapp | + | |width=10% align=center bgcolor=#eee|morrison, rossberg, yapp |
|} | |} | ||
| − | |||
| − | + | == Scope of the Migration Project == | |
| + | This project attempts to modernize our infrastructure migrating existing documentation from Docbook XML to AsciiDoc in Antora. | ||
| − | == What is in scope? == | + | === What is in scope? === |
The minimum scope of the project is migrating our existing Docbook XML docs in our [https://github.com/BRL-CAD/brlcad/ repository]. This includes: | The minimum scope of the project is migrating our existing Docbook XML docs in our [https://github.com/BRL-CAD/brlcad/ repository]. This includes: | ||
| Line 51: | Line 49: | ||
* Working with dev team to establish required Github and/or CMake logic that deploys docs to Antora | * Working with dev team to establish required Github and/or CMake logic that deploys docs to Antora | ||
* Working with dev team to coordinate deployment of Antora to brlcad.org | * Working with dev team to coordinate deployment of Antora to brlcad.org | ||
| − | |||
* Maintaining a public log of and writing up a summary of project outcome | * Maintaining a public log of and writing up a summary of project outcome | ||
| − | == What is not in scope? == | + | === What is not in scope? === |
There are extensive docs not in Docbook XML format in our repository, on the [[Main_page|website wiki]], [[Documentation|in other formats]], and in other files that are desirable and may also be migrated (e.g., for testing purposes), but they are secondary priority and need not be considered in scope. | There are extensive docs not in Docbook XML format in our repository, on the [[Main_page|website wiki]], [[Documentation|in other formats]], and in other files that are desirable and may also be migrated (e.g., for testing purposes), but they are secondary priority and need not be considered in scope. | ||
Also not in scope is technical administration, maintenance, and installation of Antora itself on our production server. This will be handled by the dev team. The technical writer will need to be capable of setting up Antora locally for development and testing purposes. | Also not in scope is technical administration, maintenance, and installation of Antora itself on our production server. This will be handled by the dev team. The technical writer will need to be capable of setting up Antora locally for development and testing purposes. | ||
| − | |||
| − | |||
We estimate that this project will take 3 months to complete. We have three mentors willing to directly help with this effort and that have committed to supporting the project. | We estimate that this project will take 3 months to complete. We have three mentors willing to directly help with this effort and that have committed to supporting the project. | ||
| − | = Measuring | + | == Measuring Success == |
As this project centers around migrating documentation, measuring success is a simple function of percent documentation converted to AsciiDoc and deployed to Antora. At present, there are 505 .xml documents in doc/docbook of the repository that require conversion. | As this project centers around migrating documentation, measuring success is a simple function of percent documentation converted to AsciiDoc and deployed to Antora. At present, there are 505 .xml documents in doc/docbook of the repository that require conversion. | ||
| − | We would consider the project successful if at least | + | We would consider the project successful if at least 80% of the existing Docbook files are fully converted to AsciiDoc, imported to Antora, and deployed online. |
| − | We would also consider the project successful if, within a year, it results in external pull requests to a migrated AsciiDoc | + | We would also consider the project successful if, within a year, it results in any (> 0%) external pull requests to a migrated AsciiDoc document. |
| − | = Project Budget = | + | == Project Budget == |
| − | We we anticipate the project requiring 3 | + | We we anticipate the project requiring 3 months of near full-time effort. As such, our budget is set at $9060 total with $7560 (84%) allocated to the technical writer and $1500 allocated to 3 volunteers ($500 each). |
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | = Additional Information | + | == Additional Information == |
| − | == Previous experience with technical writers or documentation == | + | === Previous experience with technical writers or documentation === |
BRL-CAD has an extensive development legacy that spans three decades. [https://brlcad.org/BRL-CAD_Bibliography.pdf BRL-CAD's bibliography] speaks for itself as to the extensive nature of our community's experience with documentation and technical writers. BRL-CAD maintains hundreds of existing documents, tutorials, guides, quick references, diagrams, presentations, books, and more that help teach fundamentals to advanced CAD topics and everything in between. | BRL-CAD has an extensive development legacy that spans three decades. [https://brlcad.org/BRL-CAD_Bibliography.pdf BRL-CAD's bibliography] speaks for itself as to the extensive nature of our community's experience with documentation and technical writers. BRL-CAD maintains hundreds of existing documents, tutorials, guides, quick references, diagrams, presentations, books, and more that help teach fundamentals to advanced CAD topics and everything in between. | ||
| Line 105: | Line 79: | ||
For many years in the early 2000's, one of BRL-CAD's leading sponsors employed a technical writer to work full time on BRL-CAD documentation. This resulted in daily interaction over many years and gave our community an appreciation for the value technical writers bring to the table. Since that time, we have continued to engaged technical writers, write technical documentation ourselves, consult with technical writers on our docs, and engage documentation contributors. | For many years in the early 2000's, one of BRL-CAD's leading sponsors employed a technical writer to work full time on BRL-CAD documentation. This resulted in daily interaction over many years and gave our community an appreciation for the value technical writers bring to the table. Since that time, we have continued to engaged technical writers, write technical documentation ourselves, consult with technical writers on our docs, and engage documentation contributors. | ||
| − | == Previous participation in the Season of Docs, GSoC, GCI, Google DocCamp == | + | === Previous participation in the Season of Docs, GSoC, GCI, Google DocCamp === |
BRL-CAD was fortunate to participate in the inaugural 2019 Season of Docs. We had a wonderful experience working with Sahibpreet Kaur to create a concise Intro to BRL-CAD. This document was instrumental in the creation of updated modeler training that has been utilized in four separate in-person and online training classes for BRL-CAD. | BRL-CAD was fortunate to participate in the inaugural 2019 Season of Docs. We had a wonderful experience working with Sahibpreet Kaur to create a concise Intro to BRL-CAD. This document was instrumental in the creation of updated modeler training that has been utilized in four separate in-person and online training classes for BRL-CAD. | ||
