Feedback please: Documentation updates and changes needed

[lwasser]

Hi Everyone - I've spent some time on the docs, and there are a handful of things that we might want to consider. I think we should create a project or milestone for docs and several sub issues.

We have a few folks @willingc and @flpm who bring a lot of open source, translation, and documentation experience to us here!!

Here is what I've learned so far:

1. Our documentation is built using Docusaurus 1.x, which is a version, I think, from 2019 when they were created. Because of that, 1.x is deprecated, 3.x exists, and there is significant work to do to migrate (as it will impact our directory structure which impacts crowdin.
2. We need to wait to migrate to 3.x until we have access to Crowdin as administrators. The files we have now are linked to translation files. We will want to develop a plan to migrate when we are ready. The wonderful @flpm from the pyOpenSci community (and other parts of the open source ecosystem too!!) is open to supporting the translation pieces once we get to that part!!
3. I was able to get a GitHub action to build the home page in my fork: https://www.leahwasser.com/all-contributors/all-contributors/, but you can see there is a problem with dueling directories. I am not sure what is going on with the double directories yet, but I do think we could move to GitHub Pages if we wanted and use all-contributors.github.io as a working website until we figure out allcontributors.org.
4. It appears as if the homepage index.html is pure HTML and not Markdown. There are a lot of hard-coded links and such there that we might want to revisit when we consider migrating. I don't know Docusaurus well enough to understand why a landing page wouldn't just be markdown! I'm hesitant to suggest mkdocs because it would require people to install Python, which isn't necessary for a JS/HTML repository. So it is simpler to stick to similar tools and languages - but let's revisit that home page design!

The fantastic @willingc is willing to help us review doc PRs as we submit them.

I'd like to suggest a path to move forward.

1. Let's form a documentation team here for everyone who wants to work on docs! Some of us can focus on translation, while others can concentrate on infrastructure to build the docs and content updates.
2. We could work on the GitHub Pages website here to see if we can get that working (I'm sure I'm missing something small). The action I wrote is here. The URL would then be all-contributors.github.io. If we can fix Netlify, that's great. I suspect a DNS issue is involved, which will require domain access on Cloudflare.
   • Speaking of DNS, the URL is paid for through 2027. So we just need access to fix things.
3. Once we get the website working again, I suggest the next step is to examine the Crowdin setup, and create a plan to migrate to Docusaurus 3.x that will also include migrating translation content.
4. Then we can create small subissues issues to allow community members to help us migrate content over.

I'm super open to ideas here on how to move forward. And to any help anyone can provide!

This is just a suggestion. I can update the plan as comments come in here as well, and once we decide, I'll create a project/set of milestone issues to work towards. ❤️

[JimMadge]

Speaking of DNS, the URL is paid for through 2027. So we just need access to fix things.

Oh, interesting. I had assumed the domain expiring was probably behind the website going down.

I agree that moving to GitHub Pages using actions is sensible here. It integrates nicely with CI and is free hosting.

I'm also not familiar with Docusaurus but I'm willing to learn. I think the order of preference is,

1. Stay with Docusaurus (assuming migrating over the major versions doesn't require starting from scratch)
2. Move to another JS-based static site system
3. Move to another non-JS static site system

[lwasser]

That makes sense to me @JimMadge i don't have a strong preference here. Let's just stick with Docusaurus as I really don't know the JS static ecosystem at all. But it is actively maintained. We will have to restructure the docs to migrate to 3.x but I think we can do that. I also now have the ability to setup github pages and any API tokens we need to build things. So perhaps we just move forward with getting @849 deployed.

[Berkmann18]

Our documentation is built using Docusaurus 1.x, which is a version, I think, from 2019 when they were created. Because of that, 1.x is deprecated, 3.x exists, and there is significant work to do to migrate (as it will impact our directory structure which impacts crowdin.

It would be worth trying to see if we can migrate the docs to v2 instead of jumping to v3 in one go.

We need to wait to migrate to 3.x until we have access to Crowdin as administrators. The files we have now are linked to translation files. We will want to develop a plan to migrate when we are ready. The wonderful @flpm from the pyOpenSci community (and other parts of the open source ecosystem too!!) is open to supporting the translation pieces once we get to that part!!

You should have admin access now.

I haven't heard anything yet from @jakebolam about the Netlify project and I don't have access to the team he set up there.

[lwasser]

It would be worth trying to see if we can migrate the docs to v2 instead of jumping to v3 in one go.

@Berkmann18 that is a great idea. I read there is a tool to migrate from 1.x to 2.x so I will try that out once we have things working on our github pages site!

You should have admin access now.
Thank you!! I do !

I haven't heard anything yet from @jakebolam about the Netlify project and I don't have access to the team he set up there.

Ok - that is fine. I think for now if we focus on github pages we can just turn netlify off completely. If Jake gets back to us at some point, that would be great because we can then redirect the DNS to github pages and setup the domain here.

In the meantime we can continue to move forward with the documentation hosted on GitHub pages. And we can focus on

1. Getting it online (we are close - docs: ✏️ fix links to doc site and small bug in footer.js #871 should fix things and if it doesn't I know what to try next)
2. Migrating to Docusaurus 2.x (i won't do that until we have a handle on the translations but I will test out the migration tool!)
3. Managing translations on crowdin. I think because we have crowdin access as managers we are good to go there too. If we really need more access, then we can move the project to a new one as well with all of the translation data. But we can worry about that when/if that comes up!

[lwasser]

Current state of docs:

• Website is partially live at : https://all-contributors.github.io/all-contributors (we could easily change it to be https://all-contributors.github.io/) if we rename the repo see docs: Rename this repo to all-contributors.github.io to support github pages #860
• Felipe is working on figuring out translation issues!
• I just submitted docs: ✏️ fix links to doc site and small bug in footer.js #871 which should fix the link to the docs (hard-linking for now to the english version)

[flpm]

I have been playing with the translation but some of it depends on docusaurus and some aspects of the current way the site is organized (e.g. homepage being a static index.html) makes it much harder to translate certain parts.

So I decided to play with docusaurus 3 and as an experiment, create an empty new docusaurus 3 site and try to move the content of the old docusaurus 1 site into it instead of modifying the old one.

So much has changed. I had to port the siteConfig.js to the new docusaurus.config.js, fix many little format details the new parser does not like about the markdown files and port the index.html into an index.js page. But I managed to get to something that builds in docusaurus 3 with no errors.

It does not look pretty, some of the css is missing and there are issues with the navigation links, but this might be feasible.

I will continue playing over the weekend. Worst case scenario this will be useful to learn everything that changed from docusaurus 1 to 3.

[lwasser]

@flpm Thank you for this effort!! Migration is a lot!

I started to play with migrating Docusaurus to v2 just using the migration tool they provided to see how much work it will be. It seems like the current site structure doesn't follow the intended Docusaurus 1.x structure. I think similar to what you have encountered, we may have to manually update everything.

Should we consider a different platform like astro which has a documentation theme. It also is hosted by Open Collective and has some corporate sponsors but is an independent project.

https://docs.astro.build/en/guides/migrate-to-astro/from-docusaurus/

I have no experience with astro; I found it after some searching. I'm keen to move to a truly open source platform rather than one that is backed by a closed source company with copyright notices in the source. I noticed astro does have language drop downs too. I'm open to pushback on this idea of course. But if we are going to do a lot of work to migrate, I wondered if we spend that effort, moving to a platform that we can learn and use and is truly open source. This definitely is different from the comment above I made about Docusaurus but at that time, I thought we could just magically migrate things and it would work with some effort. Now I think it will be significant effort to migrate.

Thoughts? @Berkmann18 @gr2m do you have any thoughts on this?

[flpm]

I did a quick proof of concept to build the site using Astro and the Starlight theme (their default theme for documentation)

What I did:

• Copied the current MD content and images
• Build with Astro using the Starlight theme (their basic doc theme)
• Did not set up translations, but Astro has a good support and the theme has a drop down selection of language
• Did not port the current homepage (in the static index.html file)
• Did not modify any CSS, so it does not look pretty, but could be fixed to match the brand

You can see what the POC code looks like here: https://github.com/flpm/astro-test/
And a live version here: https://allcontributors.medianoche.org