May 9, 2010

Documentation! it should be TDDD

UPDATE: I shouldn't have said what I said about RJBS and have apologized publicly

Test Driven Development should be Test and Documentation Driven Development. I don't want to read your code to figure out how to use it. I don't really care if you write the Test, documentation, or the feature first. But you should do all three before moving on to the next one.

I'm gonna pick on Dist::Zilla this seems like a very good tool. Except it's documentation is so sub par it's not funny. The new documentation is quite good, although, I have not decided that I like the 'choose your own adventure' format. However none of the documentation on CPAN is good. It ranges from significantly less than the new tutorial, to virtually non-existant, to completely inaccurate.

You know what? It's not acceptable not to write documentation, especially not when you were apparently paid to do it and have shown that you are capable of doing it. Some people I've talked to think not documenting things is ok. I don't think it is, and it's yet another one of my unpopular opinions. Sure you can not document them... If someone else has volunteered and is actually doing it.

Yet maybe this is one of the reasons perl has fallen by the wayside. Documentation is usually either cryptic, incomplete, or inaccurate. Even the core docs like perlintro has inaccurate and potentially damaging information. Why are we so surprised that so many people don't know how to program perl in a modern way if the documentation is so bad?

Documentation should explain who, what, when, where, why and how. Who should use this module, what they should use it for, when they should (and shouldn't) use it, where they should use it, why they should use it, and how to use it. Unfortunately most documentation fails at all but the how, and the what. Who is an Abstract, and Description thing, you should consider who doesn't need it. Why why can be tightly related to who, but really I want to know why this module and not another, consider who needs a templating engine vs why it should (or shouldn't) be HTML::Zoom. When is also closely related to the previous 2 and will probably be answered with them, although consider when to use a for loop vs when to use a while. Where could be anywhere from top of file, to your view in a catalyst program. How is obviously the actual code and should be covered in the synopsis. Sometimes you'll have to think if you've answered all these, but if you manage to answer them all in a comprehensive and complete manner then you're documentation is probably good enough to be useful.

I don't expect people to be perfect in this, but some effort is better than none. Also if you write documentation, you may end up answering less questions, and save people many hours finagling a problem.

I'm sure even my modules fail to meet my own standards.

The best documentation I've seen is PostgreSQL's and Gentoo's.

UPDATE:
perlintro was fixed in 5.12.1

25 comments:

  1. Without going into the specific examples I agree that in many case the documentation is not the best or at least not beginner friendly.

    I know this is the case with Padre as well but I think instead of antagonizing the developers we should find a way to encourage the inclusion of other people in the projects.

    In many cases people who are new to a project will make a better document writers or testers. Getting more people involved in every CPAN module will also increase the likelihood of long term life for the module as it won't be dependent on the interest and knowledge of a single developer.

    ReplyDelete
  2. Oh? Documentation sucks? You probably didn't see it coming, but PATCHES WELCOME :)

    On a serious note a lot of projects evolve from being personal toys. If I am writing something I am not even *thinking* to put initially on CPAN, I *definitely* will not document it, heck most likely won't even test it.

    I'm sorry Caleb, but this set of posts lately comes through as extremely whiny and obnoxious. OSS is a team effort. The software you use for free is not written by a lonely fat naked bearded guy in a basement. It is built brick by brick by many hands. Instead of burning electrons to spew unadulterated FUD about how everyone owes you something, become part of this awesome pool of minds. It's an exhilarating experience, try it some day.

    Alternatively do everyone a favor and at least grow up.

    ReplyDelete
  3. You know, sometimes there are Perl modules with lacking documentation. However, I believe your point about Perl being left aside because of it is complete bullshit.

    The proven and established modules all have great documentation. I mean, the docs are *really good*. This is one of the features of the Perl community I miss the most when dealing with other languages: the ability to write useful, informative docs.

    So, yeah, most Java libraries have tons of pages of docs. However, it's all useless boilerplate such as method signatures and so on. In Perl land you have good docs instead - but authors only bother writing those docs when they feel it's already worth the effort (because, you know, people prefer doing cool things like inventing HTML::Zoom with their volunteered time instead of writing docs).

    ReplyDelete
  4. So, you think that dzil's "new documentation is quite good", and then complain about the rest of the docs; but your dig about how rjbs was "apparently paid to do it" contains a link to a post whose contents make it clear that the TPF grant funded the new user guide, which is the part of the docs that you actually like.

    It's easy enough to write off arguments that contain this kind of personal sniping when they're accurate. Inaccurate ones? Yeah, good luck with that.

    ReplyDelete
  5. @Peter How am I supposed to write a patch for documentation if I don't know how to do it myself because there is no documentation?

    @nilsonsfj you missed the part where I pointed at perlintro? I could point at perlre too... and I'm sure if I spent enough time with them I could find inaccuracies throughout Perl docs.

    @Hans yes I said the new docs were good. However, none of them have been ported to the pod docs. This is like 90% copy and paste, and it's still doesn't provide 100% coverage, in fact looks like it covers maybe 50%.

    In my opinion... if it's not documented it doesn't EXIST. I don't care to dig through your code to figure out how it works to use it. I like to be able to say RTFM but I can't say it when I know the Manual Has F*ing Problems!

    ReplyDelete
  6. oh and in the time you all spent on writing these paragraphs to diss my opinion. You could have been writing a paragraph of documentation somewhere.

    ReplyDelete
  7. FWIW I wrote 3 paragraphs of documentation while I was reading through your post, because it was _just_ _that_ _devoid_ of content.

    ReplyDelete
  8. Please quote where I dissed your opinion.

    You said that rjbs took money to write docs and then didn't write them. I corrected this misapprehension.

    It's not very polite to accuse someone of what is essentially theft, especially in a public forum, especially in the open source community where one's reputation is such a huge part of their ability to find future employment.

    This is why I said that you should stick to your argument instead of including personal attacks.

    ReplyDelete
  9. As always in open source, if you want something either pay someone, do it yourself, or ask someone nicely.

    All of this doesn't qualify as "asking nicely."

    ReplyDelete
  10. @Hans Theft? I didn't say theft... we apparently don't agree on the definition of theft, either. I said he didn't do it completely enough. But people 'round here are constantly using the excuse "It's free and I'm not paid" well... he got paid. I've also heard this "I'm a library writer" dzil is not a library it's a command. Dist::Zilla is listed on Task::Kensho which means it should be among the best we have to offer, and functionality wise it seems to be quite good. But what good is functionality if you can't figure out how to use it? Maybe I shouldn't have said that... Honestly, I wouldn't care if the documentation was on cpan or on dzil.org... but the documentation that I went looking for last night doesn't exist. Obviously before the grant documentation was even sparser.

    ReplyDelete
  11. @Robert Ask Nicely? all that gets me is "patches welcome" or no response at all. So I'm done asking nicely. Frankly, I'm done asking. I do enough for open source that I'd think people would stop calling me a leech. I've improved documentation in some modules.

    You people think it's whining. I think you guys whine about people asking you to document your shit. Or about asking you to be willing to patch it when there's a flaw they don't know how to fix (e.g. how am I supposed to write a patch to document a feature when I don't know how that feature works).

    Actually if some attitudes started changing I might be willing to write docs. But as of right now I'm so fed up with the "patches welcome" and the "I'm not responsible" and the "I don't like writing docs" attitudes. Why the f* would I want to help? Once I've figured it out there's nothing in it for me. You guys know how your software works so what's in it for you? after all, you don't really seem to care if anyone else uses your software. It's just there in the event someone might find it useful, and can support themselves.

    ReplyDelete
  12. On Saturday night I could not sleep and I was watching a documentary about James Cook. At that time scurvy was a great problem for sailors and he had that idea to cure it with sauerkraut. The problem was, the sailors would not want to eat it. He could force them to eat it by a command, but instead he made it served everyday at the captain's mess and only optional for the rest of the crew. Soon everyone demanded it.

    ReplyDelete
  13. @zby interesting analogy? although I'm not really sure how the story is meant to apply.

    ReplyDelete
  14. "@Robert Ask Nicely? all that gets me is "patches welcome" or no response at all. So I'm done asking nicely. Frankly, I'm done asking. I do enough for open source that I'd think people would stop calling me a leech. I've improved documentation in some modules."

    Then you're done getting help. At least with me. I haven't called you a leech or any other name, while you insist on displaying this rather insulting behavior.

    "You people think it's whining. I think you guys whine about people asking you to document your shit. Or about asking you to be willing to patch it when there's a flaw they don't know how to fix (e.g. how am I supposed to write a patch to document a feature when I don't know how that feature works)."

    Simple: Ask, read the source, or don't.

    "Actually if some attitudes started changing I might be willing to write docs. But as of right now I'm so fed up with the "patches welcome" and the "I'm not responsible" and the "I don't like writing docs" attitudes. Why the f* would I want to help?"

    That's your choice. Lots of people chose not to, and it's their absolute right.

    "Once I've figured it out there's nothing in it for me. You guys know how your software works so what's in it for you? after all, you don't really seem to care if anyone else uses your software."

    I don't care who or if anybody uses my software. I publish it because I already wrote it to solve problems for me, and I have no reason to keep it for myself. Especially since the software itself builds on the things the community already provided me with.

    I do care about documentation, I do care about bugs, I do care about features. I don't care about rude people trying to get their way by name-calling.

    ReplyDelete
  15. Well, "name calling" in the symbolical sense. Just to clarify because I can already see you getting even more irritated by that.

    ReplyDelete
  16. @Robert I'm really not sure why you think I'm calling someone names. I've had people call me a few. Maybe I am and am just not realizing it. However, I'm pretty sure that being called an "entitled asshole" for requesting an addition to documentation, is name calling. I wouldn't be surprised to say "extremely whiny and obnoxious" might also be name calling.

    "Simple: Ask, read the source, or don't."

    You should know that I have asked for help many times. I don't think asking someone to go source diving to figure out how to use something is an acceptable answer.

    ReplyDelete
  17. "@Robert I'm really not sure why you think I'm calling someone names. I've had people call me a few. Maybe I am and am just not realizing it. However, I'm pretty sure that being called an "entitled asshole" for requesting an addition to documentation, is name calling. I wouldn't be surprised to say "extremely whiny and obnoxious" might also be name calling."

    You might not have used curse-words, but semantically your attitude is very insulting to the people who already have spent hours of their free time to give something to the community. But you deem it "not acceptable" that they then stopped before writing documentation.

    You weren't called those things for simply asking a question. You were called that because you've displayed the same attitude you are displaying over and over, that we owe you something. If you're tired to hear stuff like "You're not paying us" or "you're not entitled to anything" might I suggest a change in your attitude? Most developers I work or communicate with are really nice fellows. So if you're having constant trouble, it might be something on your end. Change yourself and you will change the universe, as they say.

    "You should know that I have asked for help many times. I don't think asking someone to go source diving to figure out how to use something is an acceptable answer."

    That's where you're wrong: it is an acceptable answer. Just because you don't want to accept it also doesn't make it so. In most cases, that's also not what I got as an answer. I mostly got "that works, but it's not yet documented." to which I usually reply "is it stable?" and depending on that I either read the source or look for another solution.

    ReplyDelete
  18. I honestly can't see any sense in your point of view.

    Are you actually saying that you would prefer that people didn't release some code at all instead of releasing it without docs?

    You know, you are free to quietly ignore any module without docs. A lot of other people will gladly read the source to find out how a nice piece of new tech works.

    So unless you're really that selfish, and think that anything which you can't take advantage of right away is crap, I think you'll have a very hard time trying to make anyone else believe that "no code release at all" is better than "code without docs". It may be useless *to you* but it sure is useful for other people.

    It's not always about yourself, you know.

    ReplyDelete
  19. And I think you are selfish for not writing documentation. Not everyone loves source diving, and your code is not as beautiful or readable as you think it is. My time is better spent reading documentation. Source diving takes more time than writing and reading documentation combined.

    ReplyDelete
  20. "And I think you are selfish for not writing documentation."

    You always phrase it that way. Are you not realizing you are actually saying "I think you are selfish for only writing and releasing code".

    You are still evading the root of the question. Do you believe it is selfish that they only wrote code for you for free?

    I'm starting to think you're not actually taking this serious. I can't really believe anyone would say developers releasing their code into the wild are selfish. They might as well just have kept it in their repository.

    ReplyDelete
  21. yes actually for the most part I do. sure it can be a public repo, but I'd pretty much rather it wasn't released until it was documented. Once it's released people use it. Once people use it has to be supported.

    I been thinking about our difference of opinions and I realized again why it is (due to people who I know agree with me) you're a Developer and I'm a System Administrator. I don't think I've written a post on this. I'm going to.

    For us undocumented software is a pain in the ass, as it causes us unnecessary time and pain.

    (in further news go firefox for saying patches welcome to implementing svg fonts long live ffie)

    ReplyDelete
  22. "yes actually for the most part I do. sure it can be a public repo, but I'd pretty much rather it wasn't released until it was documented."

    Why? There's nothing for you to gain, except that you have to skip those projects you deem not "acceptable." On the other hand, lots of people would lose valuable code and contributions if everyone would follow your request.

    "Once it's released people use it. Once people use it has to be supported."

    Nope it doesn't. That's again your mindset that somehow tells you that since you found it on the internet, and someone gave it a version number, you're entitled to support.

    "I been thinking about our difference of opinions and I realized again why it is (due to people who I know agree with me) you're a Developer and I'm a System Administrator. I don't think I've written a post on this. I'm going to."

    That might very well be, but it still doesn't support your case.

    "For us undocumented software is a pain in the ass, as it causes us unnecessary time and pain."

    For us documenting is a pain in the ass. Often writing the software has already been enough of a pain in the ass. Having written the software we don't have to suffer that pain again. We decide to share our solution with the public, so others might find it useful to ease their pain. Why again do you feel your time and your pain weigh more than ours? If it were less pain for you if the software would never have been released, simply don't use it.

    ReplyDelete
  23. You realize that right now we're just going back and forth saying "who are you to say that your time is more important than mine".

    Sys Admins have to support code that programmers write, and we don't always get to choose what code that is. Someone always ends up supporting it. We get to support the undocumented legacy crap written in the 90s. We get to support code that was written by companies no longer in business or at least definitely no longer supporting that product.

    ReplyDelete
  24. "Sys Admins have to support code that programmers write, and we don't always get to choose what code that is. Someone always ends up supporting it. We get to support the undocumented legacy crap written in the 90s. We get to support code that was written by companies no longer in business or at least definitely no longer supporting that product."

    So do I. I share the pain. But I still have yet to understand what entitles you to dictate what someone releases to the public.

    And I know that we're going back and forth, but I don't want anything from you, it is you that wants something from me/us. I'm not in any way saying my time is more valuable than yours, you are the only one who seems to assume that.

    ReplyDelete
  25. I find it amusing that I'm being slated as the selfish one here. I do open source work for other people. If I were doing it for myself it wouldn't get done. On the other hand everyone who's calling /me/ selfish seems to do it for themselves and releases it on a 'why not'. But I'm the selfish one?

    That's kinda like donating something to a local charity because you were done with it, instead of throwing it away, imo. As opposed to buying something new for the local charity. I suppose both donations are needed, and I'm acting a bit like... I know you make enough to donate a brand new (whatever) instead of this used thing .

    Obviously not a 1 to 1 analogy because used software is the same as new software, and you keep to get using it regardless. However, I do feel you're saying "Hey I'm donating to the charity here, just be happy I'm even giving you this used (whatever)."

    I've been pushing packages to arch for months now, hundreds of them, technically everyone could do what I'm doing themselves, but I do it to make their lives easier. They don't have to learn how to use a new tool, because of me (I hope). I don't have to do it. I could easily just use the tool myself and not give back. It takes a daily effort on my part to do this, and I don't do it because "why not". Why not isn't a good enough reason, I feel that's akin to donating my trash to charity. Then again someone's trash is someone else's treasure.

    I don't ask that you document stuff for /me/ doing anything for /me/ is certainly the wrong reason. Do it for everyone but yourself. Answer me this? would you rather have people give you documented software? or undocumented. I'd be really surprised to hear someone say the latter.

    As soon as I get this RAID working (and it's taking way to long due to what seems to be lack of documentation ) I'm going to attempt making a Test:: package that lets you use pod example's as tests. So that you can write documentation instead of the tests, and accomplish the same thing.

    ReplyDelete

No trolling, profanity, or flame wars :: My Blog, my rules! No crying or arguing about them.