Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update and extend design documents #274

Open
wants to merge 3 commits into
base: main
Choose a base branch
from
Open

Conversation

Nicoretti
Copy link
Member

✔ Checklist

  • Have you updated the changelog?
  • Have you updated the cookiecutter-template?
  • Are you mentioning the issue which this PullRequest fixes ("Fixes...")

Note: If any of the above is not relevant to your PR just check the box.

@ckunki ckunki changed the title Update and extend desing documents Update and extend design documents Nov 12, 2024
doc/design/index.rst Outdated Show resolved Hide resolved
Copy link
Contributor

Choose a reason for hiding this comment

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

Is there a specific reason why you didn't simply add the new/additional design updates to the existing file design.rst?

Copy link
Member Author

Choose a reason for hiding this comment

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

Yes, I thought it might be clearer to understand the evolution. Additionally, it potentially removes the trap of reverting back to something we had previously tried because a new person might think it is a "better" solution, even though it was already tried/used for a while and evolved to the current state.

Copy link
Contributor

Choose a reason for hiding this comment

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

I would prefer having the design in a single version, not reflecting the history.
Compare to implementation, test, and documentation which also AFAIK always only reflect the latest state.

However, anticipating future regressions in design, i.e. trying out an approach that already has been evaluated and discarded, is valuable in my eyes.

Would maybe a section Design Decisions make sense here? I think it's perfectly OK, to just describe there what already has been evaluated and discarded and why.

Co-authored-by: Christoph Kuhnke <[email protected]>
Copy link
Contributor

@ckunki ckunki left a comment

Choose a reason for hiding this comment

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

Sorry, still added a question.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants