Makoto Nozaki

Peter Rabbitson sent me this idea:

I can not think of anything qualifying as doesn't have to be a huge Perl project* However, I have an idea which unquestionably will benefit the Perl community immensely, yet has a remarkably low barrier to entry (mainly one thing - patience). I propose that someone applies for a grant in the role of DBIx::Class re-documentation project lead.

I have had inklings of "there got to be a better way to do things", but it wasn't until I read this meditation by BrowserUK that it dawned at me: Fixing up the better-than-most-but-still-terrible documentation of DBIC is a ~200 person-hour undertaking, which on top of that requires someones fresh eye. Given that DBIx::Class is a "staple-module" in the contemporary Perl ecosystem, I believe it is reasonable to expect for the TPF to "pick up the tab" if someone with the right qualifications steps up.

So what is wrong with DBIC's documentation anyway?

• Lack of entry level architectural documentation steering a beginner towards most effective use of this library
  • It is not clear DBIC is not exclusively an ORM
  • It is not clear what is the primary problem it is intended to solve
• Lack of a consistent overarching approach to the subject - the current docs are riddled with localized fixups, completely ignoring the "larger picture". As examples consider:
  • https://github.com/dbsrgits/dbix-class/pull/21#issuecomment-15849436
  • https://rt.cpan.org/Ticket/Display.html?id=63843#txn-867585
  • or perhaps https://rt.cpan.org/Ticket/Display.html?id=83767#txn-1188058
• Lack of documentation clearly delineating the components, and extension points
  • Lack of clarity what is and what isn't safely overrideable
• Too many "learn by doing" tutorials, unaligned and sometimes even conflicting with each other
• Lack of proper versioning markers in the reference documentation (X available since version such and such)
• Lack of consistent documentation of method signatures
• Inconsistent/incomplete exception texts: Ideally a DBIx/Class/Diag.pod modeled on 'perldoc perldiag' as a central exception text repository (though note - categorically no exception objects)
• Worst part - a number of other problems that I am completely unaware of, as I know the source code inside-and-out, and can only notice the "disconnect" based on questions being repeatedly asked on IRC So what would the ideal candidate for the job would look like?
• You have general familiarity with Perl conventions and "perlish documentation practices" You have decent understanding of SQL, ideally being able to follow this presentation in its entirety
• You are able to dedicate large contiguous blocks of time to the project
• You are not afraid to ask followup questions and followups to the followups, until you have a solid understanding of the thing you are actually trying to document.
• You have little experience with DBIx::Class - this is not a typo: the cleaner your slate is when starting, the better you will be able to grasp the very essence of this library and be able to present in a language accessible by those who will be consuming your work in the future. I believe the work needs to at least be able to capture things like:
  • DBIC is decidedly not a classic ORM
  • DBIx::Class::Core is an under-designed reference implementation
  • DBIC in no way mandates a properly designed schema
• You are patient
  • It is of paramount importance to ensure that the documentation does not become worse than it is now. This will likely involve multiple iterations to ensure code and documentation agree (in case of disagreement code always wins, but the goal is to eliminate all such mismatches in the first place)
  • Moreover it is quite likely that your work will not show up on CPAN several months (up to a year) after the grant is successfully completed. The library is the bedrock of hundreds of businesses worldwide, hence the current architect is extremely conservative in both matters of code and docs. What will the project provide to a successful/approved applicant?
• Authority to demand full and timely answers to any questions you they have arising from the current documentation, code, or comments.
• Unlimited access to a person with complete (as in "familiar with every single line") knowledge of the codebase. What else is missing?
• Probably a grant manager - while being versed in all things perl5, I am rather terrible at progress reports, and other bureaucracy. Besides the "unlimited access to answers" will keep me busy enough as it is.

So... any takers? Praises? Flames? :)))

Cheers Peter "ribasushi" Rabbitson Principal DBIx::Class cat herder

* In fact I strongly believe that work taking "a few weekends" can not possibly benefit the community, and framing the requests this way actively hurts the grants but that's a whole another topic.