Skip to content

[DOCS] Add new pages for the setup in three different use cases to documentation#2066

Open
Schira-N wants to merge 6 commits into
mainfrom
feature/2064-add-new-pages-to-documentation
Open

[DOCS] Add new pages for the setup in three different use cases to documentation#2066
Schira-N wants to merge 6 commits into
mainfrom
feature/2064-add-new-pages-to-documentation

Conversation

@Schira-N
Copy link
Copy Markdown
Contributor

This is about creating three different setup pages.
In follow-up PRs, the content of the pages will be reworked.

@Schira-N Schira-N self-assigned this Mar 28, 2026
@Schira-N Schira-N requested a review from a team March 28, 2026 15:50
@Schira-N Schira-N added the documentation Improvements or additions to documentation label Mar 28, 2026
@Schira-N Schira-N moved this to In Review in Best Practices code sprint Mar 28, 2026
@coveralls
Copy link
Copy Markdown

Pull Request Test Coverage Report for Build 23688680772

Details

  • 0 of 0 changed or added relevant lines in 0 files are covered.
  • No unchanged relevant lines lost coverage.
  • Overall coverage remained the same at 46.179%

Totals Coverage Status
Change from base Build 23688659250: 0.0%
Covered Lines: 139
Relevant Lines: 301

💛 - Coveralls

@oliverklee oliverklee changed the title [TASK] add new pages for the setup in three different use cases to documentation [DOCS] Add new pages for the setup in three different use cases to documentation Mar 28, 2026
Copy link
Copy Markdown
Contributor

@oliverklee oliverklee left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Please let's add them one by one. That way, we can keep the PRs smaller and merge the changes faster.

@Schira-N
Copy link
Copy Markdown
Contributor Author

Sorry, I don't see the reason, why commits of documentation should be split into tiny chunks.
For me, even the existing commit is needlessly small.
I think, textual changes have to be handled differently than code changes.

I would rather commit the whole changed documentation in a single commit.

The reason: Only then the full picture is visible and only then sensible improvements can be applied. (I am absolutely open to further improving the documentation and changing things to the better!)

Working with texts goes like this: The autor creates a text. The proofreader reads through the whole text and creates a bunch of questions, suggestings and change requests. The autor, than creates a new version of the text, based on all the comments. This circle will be continued until both are satisfied.

Of course: The proofreader will need some time to read through the whole stuff. In our case, he needs to create the generated documentation first and commenting on that is technically not so easy, I admit. Maybe, using screenshots with added notes would be a way to go... Doing a review this way will require surely 30min or more.

@oliverklee
Copy link
Copy Markdown
Contributor

After having a quick glance at these changes, I think we still need to make some changes both to the naming of the parts as well as the contents of the parts. And review time/effort roughly grows quadratically with the size of the change.

So I'd prefer to split this PR up so we can get the separate parts merged faster.

(If you're not willing to split this up, we'll need to bite the bullet, put more time into the reviews, and merge the changes later.)

@oliverklee
Copy link
Copy Markdown
Contributor

We could also add almost-empty parts as placeholders in a separate PRs first. That way, we can work out the naming first without also having to think about the specific contents.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation

Projects

Status: In Progress

Development

Successfully merging this pull request may close these issues.

4 participants