Process #1

New Issue

jolheiser · 2023-03-27T18:35:43Z

jolheiser commented

2023-03-27 18:35:43 +00:00

We need to figure out a sustainable process for this new documentation.

I would prefer keeping the docs in the main repo, a low barrier to entry is (imo) extremely important for people contributing to docs. Docs are somehow always
a. the lowest hanging fruit for contributions, yet
b. one of the least contributed-to facets of a project
With that in mind, I don't think we can get around some minor hackery to extract the docs from the main repo into something docusaurus can use.
- Looking at Woodpecker, we have a dedicated docs folder for old versions, which imo isn't ideal

My initial thought is to convert all the docs in the main repo to simple markdown files (with frontmatter, presumably), or more simply something that you could theoretically copy/paste into docusaurus and it would "just work" assuming the config is set up correctly here.

I by no means have this all the way thought out, so feedback is very welcome!

We need to figure out a sustainable process for this new documentation. 1. I would prefer keeping the docs in the main repo, a low barrier to entry is (imo) extremely important for people contributing to docs. Docs are somehow always a. the lowest hanging fruit for contributions, yet b. one of the least contributed-to facets of a project 2. With that in mind, I don't think we can get around some minor hackery to extract the docs from the main repo into something docusaurus can use. - Looking at Woodpecker, we have a dedicated docs folder for old versions, which imo isn't ideal --- My initial thought is to convert all the docs in the main repo to simple markdown files (with frontmatter, presumably), or more simply something that you could theoretically copy/paste into docusaurus and it would "just work" assuming the config is set up correctly here. --- I by no means have this all the way thought out, so feedback is very welcome!

techknowlogick commented

2023-03-27 20:28:16 +00:00

A agree with your assessment re: reasons to keep docs in the main repo, hence why I have the CI converting the docs from the main repo into a format acceptable by docusaurus.

This approach means that we can, in the future, have tea cli, act_runner, and other related tools have docs in their specific repo, and then pull them all together into this one site. Additionally, we can still keep the docs in a hugo acceptable format and build/bundle the docs on gitea build/release.

A agree with your assessment re: reasons to keep docs in the main repo, hence why I have the CI converting the docs from the main repo into a format acceptable by docusaurus. This approach means that we can, in the future, have tea cli, act_runner, and other related tools have docs in their specific repo, and then pull them all together into this one site. Additionally, we can still keep the docs in a hugo acceptable format and build/bundle the docs on gitea build/release.

jolheiser commented

2023-03-27 20:35:26 +00:00

I hadn't thought of adding docs from other repos, but that would also be great!

wrt hugo-compatible, the reason I wanted to start this discussion was to figure out whether we wanted to deal with all of the idiosyncrasies of Hugo and Docusaurus vs simplifying the Docu ingestion process and going all-in.

The shell scripts here work (and again a huge thank you for that), so there's certainly no rush, but would it be easier to maintain if we no longer had to worry about Hugo at all?

I hadn't thought of adding docs from other repos, but that would also be great! wrt hugo-compatible, the reason I wanted to start this discussion was to figure out whether we wanted to deal with all of the idiosyncrasies of Hugo _and_ Docusaurus vs simplifying the Docu ingestion process and going all-in. The shell scripts here work (and again a huge thank you for that), so there's certainly no rush, but would it be easier to maintain if we no longer had to worry about Hugo at all?

lunny commented

2023-03-28 00:08:09 +00:00

A agree with your assessment re: reasons to keep docs in the main repo, hence why I have the CI converting the docs from the main repo into a format acceptable by docusaurus.

This approach means that we can, in the future, have tea cli, act_runner, and other related tools have docs in their specific repo, and then pull them all together into this one site. Additionally, we can still keep the docs in a hugo acceptable format and build/bundle the docs on gitea build/release.

I don't think we need always to keep compatible with hugo. I mean, once the new docs site ready, we can change main repositories docs as a docusaurus folder directly. Since docusaurus supports mono repos, so it's a good idea to merge all documentation as in one. But we need to consider about the webhooks. How to and when update this docs site?

> A agree with your assessment re: reasons to keep docs in the main repo, hence why I have the CI converting the docs from the main repo into a format acceptable by docusaurus. > > This approach means that we can, in the future, have tea cli, act_runner, and other related tools have docs in their specific repo, and then pull them all together into this one site. Additionally, we can still keep the docs in a hugo acceptable format and build/bundle the docs on gitea build/release. I don't think we need always to keep compatible with hugo. I mean, once the new docs site ready, we can change main repositories docs as a docusaurus folder directly. Since docusaurus supports mono repos, so it's a good idea to merge all documentation as in one. But we need to consider about the webhooks. How to and when update this docs site?

silverwind commented

2023-06-09 11:47:57 +00:00

Docs need to stay in the main repo. I wouldn't actually mind also having docasaurus there, replacing hugo eventually.

jolheiser commented

2023-07-21 04:02:54 +00:00

Ongoing with this topic, I propose that once a version has been released (or after we drop official support?), we move the docs from that branch to this repo directly.

It means less cloning, and theoretically nothing much should change from that point on for that version of the docs.
Plus, if we ever have to do a larger refactor, it will be easier than a state where version X had X layout, version Y has Y layout, etc. as we continue to evolve the docs.

Note that I'm referring to the main repo, auxiliary repo docs probably don't need the same treatment.

Ongoing with this topic, I propose that once a version has been released (or after we drop official support?), we move the docs from that branch to this repo directly. It means less cloning, and theoretically nothing much should change from that point on for that version of the docs. Plus, if we ever have to do a larger refactor, it will be easier than a state where version X had X layout, version Y has Y layout, etc. as we continue to evolve the docs. Note that I'm referring to the main repo, auxiliary repo docs probably don't need the same treatment.

👍 1

lunny commented

2023-07-21 08:18:19 +00:00

But the event is difficult to catch?