Identify target audience #338

pdl opened this Issue Sep 15, 2012 · 2 comments


None yet
2 participants

pdl commented Sep 15, 2012

TB2 is big. There's a lot to get your head round, and some of it is quite abstract.

It seems the TB2 documentation could be improved by indicating the target audience for each module (or subsection, where that's not good enough). For example, who should create and who should use the formatter object? As far as I can tell, these are the options.

  • TB2 authors, i.e. mostly @schwern
  • Test Module Authors, i.e. people writing modules (probably in the namespace Test::) to be used in .t files.
  • Test Script Authors, i.e. people writing tests for any module
  • End Users, i.e. people who have just typed cpan install AAAAAAAAA

Obviously, there's some overlap, and indeed we hope end users will sometimes see a FAIL, investigate, patch a bug and get slowly sucked into becoming a package maintainer. But from the point of view of the role the person acting in, it would be good to make it clear that "this goes in your test script, it will influence the behaviour of LOther::Roles" and "this doesn't go in your test script. This is for people writing modules that your test script uses", etc.

  1. Do you agree this is useful?
  2. Are the above roles the correct ones?
  3. Is there an easy schematic hidden somewhere that can be used to add this info to the docs?

pdl commented Sep 15, 2012

Is there an easy schematic hidden somewhere that can be used to add this info to the docs?

Possibly this large diagram:


schwern commented Apr 23, 2013

Yes, your list of audiences is correct.

"Test Module Authors" comes in two flavors. First are people who just need to write new test functions. All they need to know if the basics of Test::Builder and none of the new stuff. They don't require any knowledge of the event system. I'd call them "Test Function Authors".

The second are people who want to mess with the entire state of the test, or to create entirely new ways of testing. Things like Test::Class, Test::Aggregate, Test::NoWarnings... they might have to play with TB2::History or write an event handler. Not sure what to call them.

@schwernbot schwernbot referenced this issue in Test-More/TB2 Mar 16, 2014


Identify target audience #66

@schwern schwern closed this Mar 16, 2014

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment