testsuite
testsuite copied to clipboard
cnti-testcatalog
docs: Unification of documentation
Join all test-related documentation into one file to unified format. Format is mentioned in related issue and is open for discussion.
Issues:
Refs: #1945
Does not afflict code, needs no testing.
What about the old docs? Duplication
We can move them to some folder "old_docs" in case they would be needed
What about the old docs? Duplication
We can move them to some folder "old_docs" in case they would be needed
I'm voting for removing old docs. This would introduce unnecessary redundancy and mess. Whoever needs to look into old docs can do it in git history/older tags.
I am down for removing duplicate docs. I think the missing/removed information from RATIONALE and other places should be added to this combined document before it is merged though.
Also, there seems to be some valid information missing from USAGE.md that explains the output from tests, etc that I feel is still good information in the docs: https://github.com/cnti-testcatalog/testsuite/blob/main/USAGE.md#syntax-for-running-any-of-the-tests and the next output should get carried over into the unified doc somewhere.
About USAGE.md: my intention wasn't to remove USAGE.md completely. Idea is to remove information that covers test categories and tests, but leave all other info in place.
Agree with deleting RATIONALE.md LIST_OF_TESTS.md and TEST-CATEGORIES.md.
I think the missing/removed information from RATIONALE and other places should be added to this combined document before it is merged though.
About missing information: two types of information weren't transferred as i consider them duplicate to other info in test:
- In RATIONALE.md, there is some text in cursive before test name, but it's shortened version of overview.
- In LIST_OF_TESTS.md, tests have expectation. I've not transferred that due to the information being mostly duplicate to reasoning and remediation. (But i see how it can still be useful, can be transferred as well if you consider it needed).
Also, "reasoning" sections should be labeled as "Rationale" perhaps? There's a reason we used the term Rationale, reasoning just sounds like another way to say Description of the test.
Reasoning vs rationale: to me - these terms are very similar in meaning, but if using "rationale" makes more sense to you - i have nothing against that.
There needs to be horiontal lines or some type of dividers between tests in the documentation. The flow of the document is hard to follow knowing when a test begins and ends in the docs since every section has Usage, Remediation, Reasoning.
Perhaps some of the redundancy could be hidden with drop downs as well for each test to limit the amount of scrolling within the doc as well. Agree with dividers, will add them. Dropdowns could be nice, but they would add significant amount of HTML tags to MD document, which doesn't look that good (in code) and could be harder to maintain:
<details>
<summary>How do I dropdown?</summary>
<br>
This is how you dropdown.
</details>
If we want header inside summary - it would be:
<summary><h3>How do I dropdown?</h3></summary>
@taylor @wavell @agentpoyo Please check if information that is missing is really needed.
About missing information: two types of information weren't transferred as i consider them duplicate to other info in test:
- In RATIONALE.md, there is some text in cursive before test name, but it's shortened version of overview.
- In LIST_OF_TESTS.md, tests have expectation. I've not transferred that due to the information being mostly duplicate to reasoning and remediation. (But i see how it can still be useful, can be transferred as well if you consider it needed).
Missing info moved, old docs deleted. Please rewiew, @HashNuke @taylor @wavell @agentpoyo
There are links to USAGE.md and likely other links scattered around the MD files not being removed that have not been updated. Merging this will break URL links to the files that are now being removed. These need to be all fixed before this is merged.
Fixed links that are affected by the change, fixed USAGE.md TOC and added link from USAGE to TEST_DOCUMENTATION, fixed some of the links that pointed to the old cncf repo (don't see too much reason to create separate PR for that small change)
Nice catch, TOC is a bit hard to check (linter for that comes as the next PR) ENV timeouts - was missing rebase. Both are fixed now.