Restructuring the Server User Documentation

pboy commented

2025-10-27 11:11:53 +00:00

Owner

Goal: Synchronizing the main and stg branch

Both are currently very different. This makes it difficult to incorporate a text into both stg and main via merge, or to transfer a text from stg to main. This can only be done manually or by cherry-picking several commits.

The main problem is that the idea of having a development branch that you can then merge into the main branch tomorrow doesn't work so well with documentation.

A possible solution could look like this:

We move the texts from stg that have not yet been integrated into main to a temporary backup area.
Then we delete stg completely and create a new fork from main. This ensures that the content, structure, commit history and log history are the same.
In stg, we initially replace all articles with a page containing a link to main.
For each new or modified article, we create an article-specific branch from main, such as “install-samba” in the case of installation instructions.
We will first merge this article into stg for reading and discussion. All changes will continue to be made in the branch.
Once a publishable version has been achieved, the article branch is merged into main and replaced with a link on stg again.
This is also feasible for long-running article branches, as the history from main can then be updated repeatedly.

Short updates that do not require discussion can, of course, still be made directly in main. Until now, the problem was that these were often not made in stg at the same time. And then there were losses during a later transfer from stg to main.

If we proceed in this manner, the workflow will become somewhat more complicated, and we will need to update our documentation on contributing to Server docs.

## Goal: Synchronizing the main and stg branch Both are currently very different. This makes it difficult to incorporate a text into both stg and main via merge, or to transfer a text from stg to main. This can only be done manually or by cherry-picking several commits. The main problem is that the idea of having a development branch that you can then merge into the main branch tomorrow doesn't work so well with documentation. A possible solution could look like this: * We move the texts from stg that have not yet been integrated into main to a temporary backup area. * Then we delete stg completely and create a new fork from main. This ensures that the content, structure, commit history and log history are the same. * In stg, we initially replace all articles with a page containing a link to main. * For each new or modified article, we create an article-specific branch from main, such as “install-samba” in the case of installation instructions. * We will first merge this article into stg for reading and discussion. All changes will continue to be made in the branch. * Once a publishable version has been achieved, the article branch is merged into main and replaced with a link on stg again. * This is also feasible for long-running article branches, as the history from main can then be updated repeatedly. Short updates that do not require discussion can, of course, still be made directly in main. Until now, the problem was that these were often not made in stg at the same time. And then there were losses during a later transfer from stg to main. If we proceed in this manner, the workflow will become somewhat more complicated, and we will need to update our documentation on contributing to Server docs.

pboy changed title from Restructuring the Server User Documentation## Goal: Synchronising the main and stg branch Both are currently very different. This makes it difficult to incorporate a text into both stg and main via merge, or to transfer a text from stg to main. This can to Restructuring the Server User Documentation

2025-10-27 21:43:28 +00:00