Richie Moluno - JSquarto: Bridging JavaScript Documentation with Quarto's Power
In this talk, Richie Moluno introduces a new tool called JSquarto, which solves common challenges developers face when documenting JavaScript projects, like the lack of support for multilingualism (especially for right-to-left languages and non-Latin scripts) and limited design flexibility. Inspired by quartodoc, Richie shows how Quarto can be used to solve these problems by generating flexible, multilingual JavaScript documentation. He also walks through how the whole process can be automated using GitHub, making it easier to keep docs up to date across different languages and formats & how it can be integrated with Crowdin, a translation management system. Talk by Richie Moluno Slides: https://github.com/Open-Science-Community-Saudi-Arabia/posit-conf-2024/blob/main/POSIT%20slide%20(1.pptx GitHub Repo: https://github.com/Open-Science-Community-Saudi-Arabia/JSquarto
image: thumbnail.jpg
Transcript#
This transcript was generated automatically and may contain errors.
is a software developer, and I work as a co-contributor to the Open Science Saudi Arabia community. So at Open Science Saudi Arabia, we basically work on open source projects aimed to improve accessibility among other non-English speaking countries with key emphasis on big speaking countries, most of which are sources can be attributed.
My wonderful team members, which are Patole, Lamees, and Gugnes, sadly. So all my team members, some of them speak more than one language, which will be very important key to note in the upcoming presentation.
So today I'll be speaking on the topic, Bridging JavaScript Documentation with Quarto's Power.
The problem with open source documentation
Now, have you ever encountered a scenario where you try to contribute to an open source project and you find out that the documentation is way, way, way out of date compared to the quite implemented features, or let's say another scenario where you're implementing a new feature on a project and you are now tasked with the responsibility of updating the documentation. And we find out that that same documentation is way, way out of date, and you have to spend more time to bring it up to date before even documenting the signature.
Some of these are the issues we face while contributing to open source projects. And this brings us to the need for very, very good documentation. So some of the qualities of good documentation we can see, a good documentation has to be very, very comprehensive, it has to be well-maintained, and this is very, very crucial to open source projects because the study also shows that 93% of developers consider comprehensive documentation as very, very, very crucial to open source projects.
the study also shows that 93% of developers consider comprehensive documentation as very, very, very crucial to open source projects.
While contributing to these open source projects, there might be some challenges and complications that we might face, one of which is the inconsistency on how updated these documentations can be. Like I explained earlier, these open source projects might be further enriching features for the documentation, so we don't just test these features by coding how these features can be used, how they can be contributed to, be adapted to other contributors.
Another issue we also face while contributing to open source projects is the difficulty in localizing these documentations, which this has more to do with presenting this documentation to a wider audience, to non-English-speaking contributors, because most of the documentation, like we all know, is well-documented in English, but they don't really fail to account for contributors from other parts of the world, which might not speak English as a native language.
Existing tools and their limitations
Although, while considering these complications and shortcomings, there are existing tools that help to mitigate these shortcomings, some of which are Sphinx.js, JPEG design notebooks, and Piddle. These tools, to some extent, help with these issues I will face while generating good documentation.
There's a little drawback with these tools, which is these tools fail to fully support JavaScript. These tools fail to fully support JavaScript.
Introducing JSquarto
So now this brings us to the question, how can we then streamline the process of generating documentation for JavaScript projects? Now, a good solution to this, a one-word solution to this, is JSquarto.
So basically, JSquarto is a tool that helps with generating documentation, streamlines the process of directing documentation with just one click, and this tool works by implementing different features common with existing tools and existing technologies, one of which is JSDoc.
So with JSDoc, you have the ability to generate documentation from basically comments within your JavaScript project. So in this case, you don't have to break your flow, having to dedicate separate extra time to code and dedicate extra time to document your code. So why not just document your code while working with projects directly?
So basically, what JSDoc does, it extracts your code comments and builds on that code comment on your documentation. So you can see on the left, you can see the code comments that describes how the function has been used, and these code comments are now extracted to form your code documentation.
So how JSquarto implements these features for JSDoc is that with one line, you can...
