Dist::Zilla is sorely lacking an entry-level tutorial or user guide. That's not to say that I would recommend its use for a first-time CPAN author - quite the opposite. It is the most arcane of all the module management systems and is aimed at (and IMHO only really useful for) the most prolific authors.
In my dream an entry-level tutorial or user guide could promote Dist::Zilla into exactly that: A recommended tool for a first-time (CPAN) module author. It doesn't matter how much magic it can do. Go for Simple problems can be solved easily, and hard problems can be solved.
| [reply] |
On the dream note I’m going to reassert, It’s a pipe dream. You can’t make advanced algebra friendly to those just learning long division. The packages could maybe gain a “wizard” script (like CPAN does on first shell run) or a lengthy checklist of configuration ideas but you can’t convey the dist, build, meta, make, synopsis, spelling, OS, tests, author tests, env, CI, repos, deps, manifest, versioning, dev versioning, et cetera to someone who doesn’t even know what those things are; and if you automate it, it’s a kind of cargo-culting. In my experience, POD is a lot to ask from first time authors and it’s dead simple. Making Dist::Zilla beginner friendly would be a, to quote a dead bird, crash course in brain surgery.
| [reply] |
...but you can’t convey the dist, build, meta, make, synopsis, spelling, OS, tests, author tests, env, CI, repos, deps, manifest, versioning, dev versioning, et cetera to someone who doesn’t even know what those things are; and if you automate it, it’s a kind of cargo-culting.
This is certainly true. But people who don't know what those things are wouldn't be the target audience for the tutorial I have in mind. I think dzil needs a tutorial which is written for people who don't know what Dist::Zilla is and how it can help them with these tasks if they emerge at all. I may well have missed something, but the documentation of Perl itself ends at perlnewmod and perlmodstyle, and this is the point where I'd love a tutorial to start off. The step by step guide in perlnewmod starts with "Start with module-starter or h2xs", and Perlmonks features How to make a CPAN Module Distribution with similar stuff. I'd like people to be enabled (neither pushed nor forced) to start with dzil new.
This is also a matter of personal preferences. I accept quite some cargo-culting when there's just a tiny chance of missing the point where the alternatives start to get cumbersome. On occasion, this pays off: The AutoPrereqs plugin alone saved me so much time that it was totally worth the migration from module-starter which I had used before. A tutorial as nysus started to write would have made my path easier.
| [reply] |
Yeah, understanding should not be a prerequisite :) Not everybody wants to be a farmer/butcher/frycook/doctor/mechanic ...
I think a more interesting idea is code instead of tutorials
Create module-starter in terms of dzil, except simpler/smarter than both, a magic burger wrapper
make solid stubby stubs for users, with solid default, fill the pod/versioninfo from smart comments (Pod::Autopod? something perlobj-smarter ? Recap: The Future of Perl 5 ?) So all new users have to do is
$ newbeedzil Snacks::Ahoy
Hi
new bee
you've picked a good name, no stopwords, no cpan conflicts, you're on
+your way
Creating
Snacks-Ahoy/lib/Snacks/Ahoy.pm
edit this, its your code, doc comments,
follow the example you like,
remember oo is optional
Creating
Snacks-Ahoy/Makefile.PL
edit this to change author name, email, license, github
All other meta files are autogenerated from these two.
to test
newbeedzil test
to preview docs
newbeedzil docs
to release to cpan
....
enjoy the magic dzil burgers
The new author only gets one choice to choose, the module name (modules names) | [reply]
[d/l] |