Robert 'phaylon' Sedlacek

First off, documentation is important. I love good documentation, and I try documenting my code as good as I can. But I do that because I want, I can, and I have the time. It is not because I have to.

As you might have noticed there’s been some talk about whether people should be free to release Open Source software the way they want to, or if we should try to bully them into compliance. Since the original author has now started to drop ad-hominems and directly attacking people who disagree with him, I will follow Gabor’s example and not link there. I’m also not gonna go into the topic of “People should be allowed to bully others. If you don’t like it, go away.” That one is left as an exercise to the reader.

I’m of the opinion that a free CPAN is what got us this far, what kept Perl alive, and what will allow it to stay alive in the future. Be it code, documentation, tests, RT tickets, or casual help on IRC. The sum of all the people doing this for free is what makes this community great.

I’ll try to demonstrate below why I think we need to further to work as a community, and the freedom and ease with which people participate. I also hope to demonstrate how cursing, belittling and being condescending to people who do something that isn’t of immediate use to you will not help.

But first off, to all people sharing any of their resources with the community, be it just code, documentation, tests, marketing, user support, or even just by keeping up with the community and using the modern tools, furthering their use and progression: Thank You! Perl needs you, and I couldn’t write Perl for a living if you all had just decided to keep it to yourselves. The Perl community is not a hive-mind, and we’re made up by many different minds.

But let’s get back to the issue at hand.

This discussion comes up a couple of times every year. It usually comes up because some poor developer thought “Hey, this code might be useful to someone else” and releases it without documentation. He has already invested time in the project, and wants others to be able to build on that. Then someone finds the module, sees no documentation, and goes on a ballistic rant like one you’d put on a pizza delivery website if they gave you cow-manure as topping instead of extra cheese.

Here are some points the proponents of a restricted CPAN make:

• I’m the customer using your product. There is an implicit support contract between you and me.

• if you’re not gonna write any documentation, I can’t use it. Why are you releasing useless software in the first place?

• People complain about not finding documentation. The lack of support is killing Perl.

• Why should I waste my time trying to figure out how the module works, if the author could just spend the time writing the documentation?

• I have deadlines to meet, and things to get done. Your stuff doesn’t help me.

Let me go into a bit of detail on why I think these assumptions are flawed:

“You owe me support”

Actually, no one does. Most Perl modules even come with a notice that they are provided without support or warranty. If I release a module, it’s not a product. I’m not selling it to you. I wrote it and figured it might be useful to others, so I put it into a public space and slapped a license on it allowing people to use it. That’s what’s commonly known as “gift.”

Giving someone a gift in no way makes you obligated to give this someone even more gifts. If you buy me a beer, you don’t owe me a sandwich. If you give me a cake, I can’t complain it doesn’t have the right sprinkles.

I know that in todays consumer-driven environment we like to have someone to blame. But to blame someone they have to have done something wrong. If you can’t blame people for not giving you anything at all, you can’t blame them for giving you less than what you would’ve wanted.

But these people have invested their time and resources into building something. And instead of keeping it to themselves, not bothering with anyone else, they chose to share it, so others might have less work to do with it out there. Sounds like a nice gesture? Sounds like something the community will be thankful for? I assume some of these people will learn their lesson and leave the Perl community when they are told to “Get off our CPAN” instead of being thanked, helped and supported in their continuing involvement in the community.

“Your code is useless”

There’s lots of things in Perl that are useless to me. The Win23 modules? I don’t use Windows. Basic tutorials? I haven’t needed them back then and I don’t need them now. The Perl 5 porters are currently even looking if they can continue to support z/OS. I can’t see that ever being of any use to me.

But I still think it’s good that it’s happening, and I’m glad there are people who are devoting their time and resources to provide us with these things. And it’s the same with code without documentation.

Code with documentation does the job and is easily accessible. Code without documentation does the job but isn’t easily accessible. No code at all is of no use to anyone. Lots of people are not comfortable reading and evaluating a module completely based on code. I have to do that every day, so I’m used to it. I can make use of a module even if it doesn’t have documentation. I can write bug reports. I can help write documentation. I can help keep the documentation up-to-date and make noise if something is unclear or unintentionally misleading.

If some people can’t because of other constraints, that’s perfectly alright. We all have to work within our constraints. But if we start policing module releases based on a single persons constraints, we’re in trouble.

Should Catalyst and Moose have not been released instead of the community working together to make them better? Should we remove Dist::Zilla because the documentation could need more work? All documentation needs more work, all the time. Just like all software needs more work.

There are lots of things that can be done with code lacking documentation:

• Simple libraries might be usable without documentation. At least for private projects.

• Someone else could come along and, instead of investing time to write code and docs, invests time to write the docs for an existing module that has none.

• Someone could build a better module, using an undocumented one as basis for how to get started. In this case the undocumented module is basically a proof-of-concept.

• Someone could fork the module if it’s good, but the opinions of the original author and the new one differ.

• If someone uploads undocumented bindings for a library “Foo,” the Perl community now has contact to a developer who knows about “Foo.”

And these are just the most obvious advantages. If the undocumented code has a dependency, the following advantages are true as well:

• The code is a searchable, live and mirrored example of a use case for the dependency. This means other users as well as the original author of the dependency can look at another example of how it is used.

• The code is testing the dependency, thanks to CPANTesters even on a wide variety of platforms and perl versions. This is even nicer if the module is used in a way not yet tested in the dependencies distribution.

The point is: Even if the code doesn’t provide an immediate solution to a single user, that doesn’t mean it has no value to anyone or the community as a whole. If I share work, it is because I don’t see any reason to keep it to myself. This to me is one of the basic pillars of Open Source. Being personally attacked is not.

“People aren’t using Perl because of this”

People aren’t using Perl for lots of reasons: TIMTOWTDI, not-shiny-enough OO syntax, because it’s old, because it has sigils, because it’s not compiled, and many more.

Lots of people spent lots of time getting documentation, testing, and best practices established in the community. They went more than the extra mile, were supportive, built better tools, and tried to communicated the reasons and advantages.

Had these people just been attacked, belittled, and had we tried to rid the Perl community of all these folks, there would be no Modern Perl movement.

It is rather amusing (FSVO amusing), that the biggest complaint I ever heard about the Perl community was rude people. I was asked more than once why people should consider contributing if all they end up with is getting hate. I find that thanks to the efforts of many people over the years, and up to this day, this has been turned this around.

This long transformation of a loosely coupled group of people into a social community of developers is what made Modern Perl possible. Perl is growing again. Maybe not yet in all statistics, but with regards to interoperability, library depth, tool-chain, testing, core development, and community spirit, there is a lot moving forward. And every tiny contribution is another step.

If there is a single mode of operation Perl does not need right now, it is hate. Since this has come up again and again, I’ll just point you here and here. In my opinion, if anything is killing Perl right now, it is anti-community behavior, and trying to make other contributors work seem worthless.

“I don’t have the time”

This is an easy one. If there is no code at all, you have to write it yourself. If there is a module that does it, but it doesn’t satisfy you, you can either help out, or write it yourself. It is all the same in Open Source, no matter if it’s about features or documentation.

Too many people seem to think of Open Source as “selling a product with a 0€ price-tag.” This could not be further from the truth. There are lots of resources on the web about this, so I won’t go into it. But just because you didn’t pay for something doesn’t mean the something is worth nothing. It also doesn’t mean the time of the developer of the module is worth nothing. Which means just because you got the first 10 hours he spent writing the code for free, doesn’t entitle you in any way to another 5 of his hours for documentation or support.

I often hear that this is not about entitlement, but I can’t but feel that it indeed is. Because this all implies that some people would rather spend their time writing something from scratch, (hopefully) documenting and testing it, instead of contributing to an existing module that is not yet sufficient for their use. If you are angry about the fact that those are the only choices you have, you are angry because you think you should be entitled to “it doesn’t exist, I have to write it” versus “It is there, tested and documented.”

Conclusion

Perl needs a free CPAN, and a community working together (socially), instead of isolating what is not deemed worthy by some.