Skip to content

Add description authoring guide and update descriptions of higher level#55

Merged
arscan merged 1 commit into
mainfrom
fi-4088-description-update-simplified
Jul 29, 2025
Merged

Add description authoring guide and update descriptions of higher level#55
arscan merged 1 commit into
mainfrom
fi-4088-description-update-simplified

Conversation

@arscan
Copy link
Copy Markdown
Contributor

@arscan arscan commented Jul 29, 2025

This is based on #52, but is replacing it because I condensed the guide into a single markdown file and clarified its purpose, and reran an LLM to update descriptions based on this. I have already manually verified each description that was updated; I do not believe further review of the descriptions are necessary.

One thing is clear to me though: this really needs to occur at test development time, as it is not very practical to change test descriptions by someone else or well after their initial creation. But i do think that this makes substantially better descriptions than what the test authors make.

This introduces a single guide: the description authoring guide, which was created by analyzing descriptions of US Core tests, as well as descriptions of existing IPS test descriptions, and formulating a set of best practices that a LLM (or human) can use to improve existing descriptions.

I then ran this on the higher levels of this repository: the test kit description, test suite description, and the higher levels of the testing 'tree'. I did not want to have an overwhelming update here, which is why I did not update all tests as is done in the other PR.

Whenever it did something incorrect, I had it update the description with what it did wrong so that it can avoid it in the future. The extra emphasis on understanding the code first before writing the description, and never assume anything about the spec but go out and read it if necessary, were put in there because of real issues that popped up. Saving that in the guidance seemed to help avoid the problem in the future.

This also does not change anything other than the descriptions, so this is a low risk PR.

@arscan arscan requested a review from Jammjammjamm July 29, 2025 03:55
@arscan arscan merged commit 1bba6a9 into main Jul 29, 2025
1 check passed
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