docs
docs copied to clipboard
nunit
Add XML Format documentation for the different test events
The XML format for Test Results are documented, but the format for the different test events are missing.
E.g.
test-output,
test-case,
start-suite,
start-test,
The test-case fragment is documented as a part of the rest result format. The new test message format is also undocumented.
Someone may want to have a think about which XML formats need user documentation versus internal documentation. I put the whole thing under "Usage Notes" but maybe it should have been split.
@CharliePoole Sorry, I was confused. Is there a page which documents all ITestEventListener XML formats? I'm starting from https://github.com/nunit/docs/wiki/Usage-Notes from the menu and not seeing it.
In my own personal taxonomy of folks who use NUnit, those who extend it are "developers" while those who use it for testing are "users". IOW, in my mind (and more important from your point of view, in my past writeups) extenders are basically the same as you and I. They use internal stuff. They don't need to be taught basics but they do need the information.
I viewed "Usage Notes" as a place to put general info for users (cf usage/user) wherease "Internals" was for developers (i.e. us and extenders).
But I put all the XML info we have into the "Usage Notes" and I'm suggesting that may have been a mistake. Adding more stuff there that is purely for extenders and ourselves would (if I'm right about having been wrong) only compounds the problem. I'm just asking "you guys" (i.e. those of us who will be around in the future) to consider whether I was wrong and whether you might not want to reorganize it.
PROS for reorganizing:
- Different audiences require different kinds of writing. Developers don't need the basics explained - at least not in every page. Users often do.
- "Breaking" changes mean something different depending on the audience.
CONS
- It requires some effort.
- Some stuff is used by both audiences.
It's really up to "you guys." :smile: