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.

Sign up for GitHub

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

Jump to bottom

Add ADR excluding examples from object descriptions #391

Merged
merged 1 commit into from
Nov 17, 2023
Merged

Add ADR excluding examples from object descriptions #391

merged 1 commit into from
Nov 17, 2023

Conversation

ahouseholder
Copy link
Contributor

This PR adds an ADR that says we're deliberately excluding examples from object descriptions. Rationale is laid out in the ADR file added, but basically it comes down to

  • keeping object descriptions short and concise
  • allowing examples to change in documentation without prompting a decision point or group versioning event
  • using the description field of an object to give enough information to distinguish it from others without placing the expectation that the description field is full documentation.

We've run into this a few times already with other decision points, but the CVSS modeling work in #377 has really highlighted the value of keeping descriptions more terse.

@ahouseholder ahouseholder self-assigned this Nov 17, 2023
@ahouseholder ahouseholder added documentation Improvements or additions to documentation enhancement New feature or request environment Project environment, deployment, CI, etc. labels Nov 17, 2023
j---
j--- approved these changes Nov 17, 2023
View reviewed changes
Copy link
Collaborator

@j--- j--- left a comment

Choose a reason for hiding this comment

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

This captures what we discussed.

@ahouseholder ahouseholder mentioned this pull request Nov 17, 2023
Merged
1 task
@ahouseholder ahouseholder merged commit df1542b into main Nov 17, 2023
3 checks passed
@ahouseholder ahouseholder deleted the adr-descriptions-exclude-examples branch November 17, 2023 16:16
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@j--- j--- j--- approved these changes

@cgyarbrough cgyarbrough Awaiting requested review from cgyarbrough cgyarbrough is a code owner

@sei-vsarvepalli sei-vsarvepalli Awaiting requested review from sei-vsarvepalli sei-vsarvepalli is a code owner

Assignees

@ahouseholder ahouseholder

Labels
documentation Improvements or additions to documentation enhancement New feature or request environment Project environment, deployment, CI, etc.
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.
2 participants
@ahouseholder @j---