Sept 11 Update: Where we are with migrating the documentation

[lwasser]

This is an update so everyone has a sense of where we are with migrating our documentation.

Domain + DNS

Many of the infrastructure pieces - Crowdin, DNS for domain and registration, netlify account are owned by a maintainer who I think is busy with lots of other things. While they aren't active here on GitHUb @Berkmann18 reached out and was able to get some help with allcontributors.org and netlify. However, we should consider

1. moving away from that netlify account as it's owned by that maintianer and they are busy!
2. DNS is also owned and paid for by them. We will need to decide if we want to pay for the domain moving forward. It's good through 2027.
3. DNS right now is routed to netlify. But they are open to moving it to GitHub pages so we could deploy from there quickly (and it works now - see leahwasser.com/all-contributors for an example (i need to update my branch but see that things work there!).

Documentation infrastructure

The documentation was originally written in docusaurus V1 but now it's at v3. Docusaurus is owned by facebook but is open source. Because moving to v2 or v3 would require a restructure of our documentation folders, and that impacts crowdin. And because we wanted to stick with a more community focused doc platform, we decided to move to Astro using the starlight theme. Astro is a community project fiscally sponsored by Open Colective and supported by companies like Netlify who also support open source!

Netlify vs GitHub pages

We decided for now it makes sense to migrate the DNS to GitHub pages for allcontributors.org. This keeps things simple and allows us to get the docs live SOON!! Jake, the maintainer who owns the domain is willing to reroute it to GitHub pages.

If we want to move to Netlify, I did apply for an open source license account. If we add a netlify badge to our docs, we can get a netlifyx open source account and I can add everyone as managers there (When we are ready for that). We have a lot of work to do now however so that can wait!

Translations

Right now @flpm is working on translations. Translations are hosted on Crowdin and we'd feel better if they were synced with GitHub. Translations also expect a certain directory structure which we have changed so there is work to do there to link up translations to the current file structure. Felipe is also working on a policy around how and when to release new languages.

The good news is that because the new astro site has a landing page! (Docusaurs had a manual html page!) we can also now allow people to translate the landing page.

There is a LOT of work to do on translations and Felipe can fill us in on things we can help with.

Where we need help with the docs

I created a set of issues which would get us to a point where we can merge the documentation progress being made on the docs-upgrade branch into main!

If anyone can help with this - please check out the milestone here

Fixing and updating images and links to the site is the biggest (i think) issue there. But circle ci will also take some time to setup (it will be much easier if we rename the repo making our baseurl / instead of /all-contributors/ .

I just opened this pr which documents how we add images and callouts to pages and how we are using astro in case it is helpful!! I would LOVE help going through pages and updating links and images etc. The issue for that is here

Help with CI (circle ci and github actions) - link check and circle ci would also be great.

I hope this is a helpful update!! ❇️ so folks know where we are. Please let me know if you would like to chip in on this! even working on a single page - updating images etc is super useful!!

[lwasser]

I also started to tag issues with help-wanted to signal where we need help!!