hanopcan
commented
3 months ago Following a discussion between myself and @fershad , who is currently our technical writer and docs maintainer, we've got these broad ideas.
I'm sharing these here in case anyone in the wider CO2.js community would like to provide advice, or additional ideas on directions we could take with this proposal.
Idea 1. Expand docs on how to contribute
We've recently updated our longer-term vision for CO2.js and produced a roadmap in google slide format. One of our key themes in that roadmap is to get more active contributions into CO2.js and build up the community. (For clarity other themes are increase the number of methodologies available within CO2.js, increase the number of data sources/external APIs & deliver a better developer experience - that's four themes in total).
We think a key way of inviting more of the community to get involved is to make these ideas we have about the future direction of CO2.js more visible, easy to understand and actionable. In other words we want to make the contents of this new roadmap open. By doing that we can encourage more contributions, both in terms of time and funding, and also contributions that help steer the general direction of CO2.js.
Up until now we've been using a github project to house our public facing roadmap. This has been helpful to date but is limited in what we can do with it. It's also rather hidden. We also don't think a google slide deck is the right format either.
Instead we're inspired by what we see a fellow open source project, Wagtail, doing with their roadmap.
One of our ideas for this proposal, is to update our CO2.js documentation website with details about our roadmap. Our docs website has around 2,500 visits per month so this feels like the right place to surface our roadmap, with additional context to encourage more contributions.
We think we could do this by pulling issues directly from GitHub via API into the docs site. Automating this process should increase the chances of us keeping these docs up to date in the longer term. This approach would also allow us to add additional context about how our community can get involved to support and present them in a more engaging, visual way.
Idea 2. How can we use types/JSDoc to generate our own docs
Another idea is to explore automating the creation of our docs, specfically our methods documentation.
We've already received some mega helpful input from community contributor @sfishel18 on how we could build some type checking into the build process in this issue and accompanying PR, which we can use as a spring board to do this next step.
Right now this part of the docs is manually maintained. Given the above, our aim to increase contributions, an improvement like this would increase our chances of keeping our docs inline with (hopefully!) and increased volume on contributions.
Plus we should document how to write the in-code documentation (so meta!) so that others could contribute to adding in the necessary code so our automated processes can pick it up. I was involved in doing this within the WordPress community at a contributor day once, and it was a great way to make a quick contribution without it taking too long (once you had the initial set-up done of course).
yashpandey06
himanshuaggar
fershad
ravjot07
SafeEHA
We've just found out about the Google Summer of Docs application process which closes on April 2nd 2024. More info.
Quite a tight turn around time, but doable!
This issue is intended to act as an open discussion place for how our CO2.js project could participate in this, and what ideas we'd like to take forward.