Grant Proposal: Test::Stream Manual

Category: Grants

Comments (4)

I'm a bit unsure of the assertion that this should not come first. Writing documentation often exposes problems with teachability or usability that can be addressed by making changes to the code.

On the other hand, the code has already been extensively tested, and changes to based on downstream breakage would, I think, be pretty minimal.

What kind of changes do you imagine occurring during the work of the other grant that would render the documentation significantly obsolete?

All the modules already have documentation. So I think the issues that can be exposed with documentation have largely been uncovered. What is left is tying the parts together in a tutorial and cookbook style. Ie you want to do X, look here for a complete guide. Right now the module docs are good reference, but there is not a lot tying each component together for someone completely new.

A good example of things that will change includes a current discussion and pull request. Currently event objects have a to_tap method. A manual would detail writing a new event, and would say to implement to_tap to control its TAP output. However in discussion it has become clear that the event to tap logic should live directly in the formatter. This would be a significant change to the manual if it had already been written.

TPF now has a history of sponsoring documentation manuals: Perlbal and RPerl (more?).

Having a documentation manual for the core piece of what should be the next testing framework for CPAN modules falls within the "quite darn useful" category. :)

This is too early. There are to many areas where things may still change IMO.

Sign in to add comment