The Best Practices suggest creating boilerplates for POD documentation. They helpfully provide some examples, and suggest differentiating between modules and applications. I can’t argue with these ideas, particularly when trying to get a group to standardize on a set, but they are not as clear-cut wins in my mind as the book make them out to be.
One thing the book suggests is that programmers don’t write documentation because of the “empty page” syndrome – they just don’t know what to write and need some structure to fill it in. That doesn’t match my experience as well as many of the other observations in the book. My experience is that engineers are outright hostile to writing documentation, and will leave the templates blank or just remove them.
My personal thought on this relates to the left brain/right brain theory. One half of the brain is logical and organized, the other half is creative, to oversimplify hugely. I think that many engineers, when writing code, are deep in the logical/symbolic space. They’re working there where they can manage the complex state of the program in their minds. At that moment, they don’t have language skills. They’re shut off, to write code. Turning them back on is effort, and breaks them out of the mental state to do coding. (This also helps explain why some error messages are so horrible – they make perfect sense if you know the state of the code, and none at all from a user’s perspective.)
Engineers seem to fight this for three reasons that I’ve noticed.
1> Coding is the fun part. You’re in the middle of having fun, and suddenly someone wants you to stop and do this boring thing you don’t want to do. They do not stop the roller coaster in the middle and make you fill out a tax form to keep going. Documentation is that same kind of interruption.
2> It interrupts the work. Switching between two mind sets is effort, and they don’t want to do it.
3> They genuinely don’t understand why it’s needed, and think anyone who does need it is “weak” and should just suck it up and read the code, like they did.
My experience is that real professionals understand documentation is important, and will write it. They will put in vague stubs or leave the boilerplate while they’re deep in symbolic thought and then come back as a second pass and write the needed words – both user documentation and technical documentation. They often re-organize or reformat the code at the same time.
How does that long digression relate to boilerplate?
If you provide boilerplate, especially verbose boilerplate such as found in the book, engineers will either never fill it out or fill it out in the worst possible way. Boilerplate needs to be a guideline and a reminder, “Hey, a license section is important, and here’s what ours looks like” not to be cast in stone and say EVERY PROGRAM MUST HAVE A COMPLETE SET OF EVERY OPTION EVER SEEN IN POD. Guess which most corporations lean to?
Being forced to fill in complex sections of POD that mean nothing for the application you’re working on is not helpful, and in fact makes it harder to face writing the documentation in the first place.
Much better, in my opinion, would be smarter tools. A POD checker that checks for minimum required sections – wait, you can use perlcritic to do this! – and ways to easily navigate your document as what the POD will look like, as well as have a list of all the common POD sections so you can realize, “Oh, yeah, this does have dependencies, I should list those.” instead of having to throw that away on every other document.
But, maybe I’m wrong.
And having said this, I now wonder if it’s possible to extend my favorite editor to do that.
I would argue against the idea that documentation is either boring or a change of mind. I see documentation as being the same part of the mind as writing code, both of them are creative and technical. Often it is easier to do brainstorming for code by writing documentation, thinking about in more human terms what you want to accomplish before also figuring out the exact code to accomplish it.
I agree with Darren. In fact, when I’m designing an API or something, I try to write the documentation first: it helps me write better code. In practise, I’m lazy and do the fun part first, which is the coding.
I actually like the boilerplate as it gives me structure. And I am not hostile to writing docs. Can’t say I love it. But I consider it to be necessary. Not all of the things in life are fun. Sometimes you have to get down and get dirty and dig a ditch, sometimes you have to write some docs.
On that note, in an organizational structure, it does not make sense to hire a dev who gets paid dev salary to write docs. It’s like getting a mechanical engineer to get down and dirty and get him to dig a ditch. That’s not money well spent.
I’d hire a junior dev to study senior dev’s code and document it (50% of the time). That gives the opportunity for jr to learn and get better.
While I agree that it doesn’t make sense to have a senior dev write the docs, I think there’s a better choice than a junior dev: A technical writer.
Every time I’ve worked with real technical writers, the documentation has been better organized, clearer, and much more effective than when some engineer got to write it. A good tech writer makes a world of difference, and the lack of them are what makes much of the Open Source documentation so unhelpful.
A good tech writer may have the same salary as a senior dev, though, which is a hard sell to a lot of management. They aren’t a cost-cutting resource; they’re a significant improvement to your product.