1. 28

    Disagree with the conclusion, the answer is much simpler. As a rule, if the project isn’t documented just assume it probably isn’t suitable for public use and certainly isn’t suitable for production use.

    Github exists to share so by all means put code in any form up for others, just don’t put it undocumented into a package manager like Hackage or PyPi where it can subtly be pulled in. That is the real harm to communities.

    1. 2

      My question is though, what do you hope to gain by sharing. Many people actually post these projects with the intent that people will use them, but then offer little or no documentation. Even many widely used projects have scant documentation (yes, few have none at all). In fact, the basis for the article came out of my own frustrations trying to use a number of open source project recently in preparation for a conference presentation - many of which were widely used (and many users of which shared my frustrations).

      1. 12

        I keep virtually all of my code on GitHub, that way, I have a backup. What few non-open source things I do are in private repositories.

        1. 13

          Or if I have multiple computers, it lets me share code between them without having to do some kind of obnoxious syncing.

          A ton of people have dotfiles repos. No, my dotfiles are not production ready. No, I’m not going to mark my dotfiles as not ready for production.

          1. 1

            Right. I think a lot of people do. What I suggested though is that you indicate with some sort of disclaimer that this is personal or experimental and you do not intend to support, maintain or document it. Makes it quick and easy for you and quick and easy for a consumer to make an informed choice about using it.

            1. 12

              This is always true with open source, no matter what. We like to pretend that it’s not true, but at the end of the day:

              THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

              There are projects that I’ve been the maintainer of with tens of thousands of users, and then life happened.

              There are all kinds of other things that point toward this, though: only one contributor, very few commits, no documentation. That says it way more effectively than any kind of disclaimer I could make.

              1. 4

                Yeah. We’ll know software engineering has made progress if we ever get to a point where we can safely omit that wording. It’s hard to imagine, right now, even with formal verification.

                1. 7

                  It’s hard to know or predict what someone will do with a piece of software. There are a finite number of requirements for a screw you buy at the hardware store. If your shed collapses because you didn’t use enough screws, that’s obviously your fault. If your website collapses because you used the wrong template engine, well how could you have known that? Obviously time to blame the author.

                  1. 3

                    Absolutely. We are in agreement. :)

                2. 2

                  There are plenty of examples where this simply isn’t true (in fact, the author clearly intended it to be shared, but didn’t bother doing any real documentation). Thus the impetus for the article.

                  1. 4

                    (in fact, the author clearly intended it to be shared, but didn’t bother doing any real documentation)

                    This is saying that it’s intended to be shared. But in the end, it’s still not offered with any kind of warranty; I can release a library with no documentation if I don’t want to write documentation.

                    1. 0

                      Of course you can. I am saying you shouldn’t. Not sure who it’s helping to do so.

                      1. 2

                        Documentation decreases the barrier to entry to using a particular piece of software. Zero documentation does not necessarily imply an infinitely high barrier to entry. If someone is motivated enough, the lack of documentation may not prevent them from reaping the benefits of the code that was shared.

                        I get that the world would be a much nicer place if we didn’t share things that were significantly lacking in quality. We should definitely continue to advocate in favor of documenting your code, even if you don’t share it. But it’s the wrong thing to should-people-to-death for. The better thing to optimize for, IMO, is to teach others how to identify whether a project is worth using or not.

            2. 5

              Because other people can reference it if their time is not valuable and they’re willing to put the time in to read the source. Code gets open sourced for a lot of reasons, and a lot of them are not necessarily for to make something that’s immediately usable in a commercial setting. How people donate their time is really not something you can expect to really control.

              Thus the above advice: If it’s not documented and you’re on the clock, assume the library doesn’t exist honestly.

              1. 4

                There are plenty of employers who look at your github activity as a quick gauge on your code/activity level outside of work or classes. Not necessarily a fan of the practice, but it is a real reason people put up code that’s not for widespread consumption.

                1. 2

                  Many users shared your frustrations, but they’re still users. Their frustrations with the project must be less than whatever frustrations drove them to use someone’s undocumented code. If enough people find this code useful, maybe they’ll consider contributing documentation back to the code base as they figure it out. If the author sees this, they may realize that if people find the undocumented draft project useful, that maybe it’s worth some effort to improve it. Or the author doesn’t care, someone forks the project, and it takes off.

                  There are many paths to useful open-source projects, and they don’t all require the author to spend an inordinate amount of time documenting every feature for a project nobody may ever see. The onus on deciding how to put together your project is still on you, not the authors of every piece of open-source code that might be relevant to your project.

                  1. 2

                    You think people publishing code are doing it for you, and want to chastise them for not bringing the quality to your standard?

                    I think it’s much more sensible to simply assume that they’re not doing it for you, but for some other reason. That is to say that I don’t think people post these projects with the intent that other people will use them, but for some other reason. Some do it because it is a convenient backup, and others because it’s the minimum needed to get a contribution, but I don’t know anyone who does it for other people.

                    And yet: I do want projects to have better documentation. I think a documentation standard is more valuable than a coding standard: We are writing for humans; the computer does what we say, but we write to express what we mean so that human beings can fix our mistakes in stating it correctly. To this end, I recommend that programmers write documentation first, and then implement the documentation, and I consider a programmer who cannot document his software to not be a very good programmer. I just don’t think this blog posting is how we get there.

                1. 6

                  I don’t agree with this, and I think the author is assuming too much about how people use GitHub. Not everybody puts their code on GitHub (or sourceforge, bitbucket, etc.) with the goal of creating a big “successful” open source project.

                  I publish essentially all of my code to GitHub. The code is free to use, but it’s on GitHub mostly for my own convenience and it doesn’t matter to me if nobody ever looks at it, and I don’t care if it’s helpful or useful to anybody else besides me. If I think a project could be useful to other people I’ll fill out the README and publish it somewhere (add it to QuickLisp, for example), but a lot of times I don’t bother. I’m not obligated to put code or documentation on GitHub, and nobody is entitle to have me do it.

                  If a project is difficult to use, isn’t documented, and you don’t have time to figure it out, simply don’t use it.

                  1. 2

                    So much this. I make stuff publicly available on GitHub because it provides me with a free backup and convenient syncing between computers. (I’d use a private repo but I’m too cheap.) I try to put at least a README in each repo though.

                    1. 1

                      My argument is that you can go ahead and continue to do this, however, make it clear that this project is not intended to be maintained, supported or documented - so, use at your own risk. It’s a simple thing to clarify, so that if I, as an end user, come across, I know this perhaps isn’t worth pursuing.

                      I’ve seen tons of projects that look like they might be real and intended for public use (some actually clearly are) but the docs are not there yet. In some cases, a developer comes across it and is like “this is exactly what I need!” It’s only after time spent trying to resolve issues that they come to realize that the developer never really intended this to be documented or maintained - i.e. it wasn’t really for public consumption.

                      1. 5

                        IMO source code is not intended for end users and is always “use at your own risk,” so I don’t feel like that’s really necessary.

                        An application’s code is not generally for end users, and if you want a full-fledged supported, documented solution to your problem, you should look at the project website or mailing list or wiki, not the source code.

                        For libraries, it’s better to use Pip, NPM, QuickLisp, CPAN, etc. or even your operating system’s package manager (or homebrew) to get a “*-dev” package. If the project owner hasn’t taken steps to get the project out to the public, they’re probably not interested in getting people to use it.

                    1. 8

                      It really is not that hard to instead of just searching for all available projects, talk to some peers and see what mature options are out there, or do the ‘research" yourself. If it is a good product and there is no documentation, and that’s a problem for you, write some. Don’t just pull some repository with version 0.0.3 and use it like a blithering idiot. It’s your product and your product alone will fail, so it’s your responsibility to make sure the code you pulled in is sane, not joe schmo who puts in 3 hours a year to this side project.

                      1. 2

                        I think the problem is with transitive dependencies, not direct dependencies. Sure, you can make sure all the libraries you use are high quality and well documented, but who’s to say that those libraries' maintainers did the same thing? It may just mean that you need to consider transitive dependency quality in the vetting process, although that would be a substantial amount of work in most cases.

                        1. 2

                          If your project is going to be put on production, where up time, and security matters you better be sure that the transitive dependencies are not a weak link. Either that or the main dependency is so popular that the issue will be resolved quickly I suppose (lookin at you React) but that is a bit like driving a volvo without a seatbelt. Storing your dependencies with your code (or somewhere), and testing before merging new dependencies might not be a bad idea. I think it’s a pretty strong given that in any platform, package manager, etc, catastrophic failure is possible, and we should be at least a little prepared for it, especially when it’s inexpensive to do so.

                        2. 1

                          My point is, though, that why are you putting it on the consumer to figure out if your project is worth using or not. It’s also not always clear, from the consumer standpoint, that a project isn’t worth using fully until they’ve already invested some time in it. It’s usually not as clear cut as zero documentation - often there is very limited or poor documentation (I’ve often cited a static site generator that I used that, once you got past the very basic getting started, you were stuck just reading the code to figure out how to use it). It’s clear looking through the issues that a lot of developers attempt to use these projects - so, what, as an open source developer, do I gain by putting a project out there that, in many case, wastes developers time or frustrates them mostly due to a lack of documentation?

                          1. 1

                            It’s always on the user to decide whether or not the project is worth using or not. The developer obviously cannot jump into the user’s brain and make the decision for them Inception-style. But there are generally some useful heuristics that you can use. How long as this project been around? Is it actively maintained? Does it have a relatively large userbase? Is it backed by a reputable tech company, etc? None of these questions is difficult to find answers to.

                            If you put code out there without documentation and somebody decides to use it, you didn’t waste their time. They wasted their own time by making a poor decision.

                        1. 3

                          FWIW I commented about disagreeing with the author’s assertions around personal projects and he has updated his wording to be more clear about that point in particular.

                          This scores points for the author with me. Being able to thoughtfully respond and change your opinion shows a willingness to learn and be open minded about things, which I find to be a big plus.

                          1. 3

                            Thanks. I appreciate that.

                          1. 27

                            Overusing Dijkstra-isms “Considered Harmful.”.

                            1. 11

                              Seriously. This could be a fantastic article but I just can’t be bothered to open anything with ‘considered harmful’ in the title anymore.

                              1. 9

                                It isn’t, so your screen worked gloriously.

                                1. 5

                                  It is already a written essay. It hasn’t dissuaded people to use the catchy phrasal template in their title http://meyerweb.com/eric/comment/chech.html

                                  1. 3

                                    The considered harmful part was partially a joke - obviously I don’t think every OSS project is potentially harmful. If you give it a chance, I’d love your opinion.

                                    1. 1

                                      I’ve used it lately, although in an article that is meant to be a direct follow-up to Dijkstra’s one.

                                      1. 2

                                        “‘Considered Harmful’ is Considered Harmful”

                                        I can see the medium.com post already.

                                        1. 3

                                          It’s been written already, long before Medium existed. That’s the link others have been offering. :)

                                          “Considered Harmful” Essays Considered Harmful

                                      1. -1

                                        spammers?

                                        1. 5

                                          Actually I think not. The web is much better at dealing with spam than email. I have my regular list of sites and feeds to poll, but when I decide I don’t like them anymore, I stop going. The web is a pull medium, not push. I only read what I want.

                                          The closest one can come to push is spamming is submitting to lobsters. But then you get down voted, filtered, moderated, etc. We’ve had limited success building shared email spam filters, but the web ones work pretty well.

                                          1. 3

                                            What is Telerik? The website makes it sound like Medium but almost the only people that post links to it only post links to it, as if spam.

                                            1. 2

                                              Telerik, AFAIK, is a company that owns Fiddler, and some ASP.NET libs, I think these articles are from their community blog, but I’m not sure. Pretty sure it isn’t spam though.

                                              1. 4

                                                It is very confusing because @remotesynth has literally only posted posts from telerik, which feels quite suspicious. however @jcs is the one that invited him here.

                                                1. 8

                                                  @jcs is the one that invited him here.

                                                  Most likely from the old invitation request queue.

                                                  At least one user was banned for spamming telerik.com links, but most of those felt very spammy advertising for Telerik products and were downvoted into oblivion. The links @remotesynth is posting about development do not feel spammy and have gotten a number of upvotes.

                                                  Are you guys claiming they are spam because of the actual content or just because they are from telerik.com?

                                                  1. 14

                                                    It seems like the people are downvoting based on the source of the articles rather than the articles themselves. I have read all of his submissions and they don’t seem spammy to me.

                                                    EDIT

                                                    Just took a look at his Twitter account, his bio seems to explain why he most/all his submissions are from Telerik:

                                                    Focused on web, mobile & JavaScript development. Work at Telerik running http://developer.telerik.com . Co-edit Mobile Web Weekly http://mobilewebweekly.co/

                                                    However, since he isn’t promoting products, but rather a community/publishing platform, I don’t really see anything wrong with it. Just my humble opinion.

                                                2. 3

                                                  @james was not suspecting the article to be spam or something. He was giving an answer to “What’s wrong with the Web?”.

                                                  1. 1

                                                    Newp, sorry i was implying that the article itself is spam. I downvote all telerik posts, and consider @remotesynth a spammer because he promotes content for commercial reasons, doesn’t contribute in any other way, and he invited other users who then also proceeded to spam telerik posts.

                                                    1. 4

                                                      I find this funny. Yes, I promote Telerik articles, but I post to lobste.rs only when I believe they are relevant to this audience. The articles are not spam and the titles accurately reflect the content, even if the site is owned by Telerik. This article doesn’t try to push Telerik products…it isn’t a pitch or marketing spam. None of the articles I post do.

                                                      I contribute to the community in tons of ways, speaking at conferences, writing for various sites, co-editing Mobile Web Weekly, promoting all kinds of posts from a variety of sources across various social media sites, authoring a forthcoming report for O'Reilly….But to you, this is somehow the work of a spammer.

                                                      Your attitude is the kind that makes it tough for those of us who try to push the companies we work for to positively contribute valuable content to the community.

                                                      1. 2

                                                        Glad to hear from you. My only contact with you is the lobste.rs community, in which this is your second comment and where you only post articles from one for-profit company. That’s spammy behaviour, and not indicative of interaction in a broader community, otherwise why wouldn’t you be posting content from your broader interactions with other technology, subjects, notes from your talks, stuff from other websites, etc. etc. ?

                                                        I find it hard to believe you don’t come across any content from anywhere else on the web that you think the lobste.rs community would like to read, maybe you could post some of that too - that would increase the value of your contributions on behalf of your employer and make you look less like a spam bot?

                                                        Maybe you’d like to come and chat about the work too, if you want your company and colleagues to interact more with the community, then come and interact more with the community?

                                                        (Consider algorithmically detecting spammers - you’d be quite likely to be a spammer, no? View the posts from any other user, then view your posts.)

                                                        Whilst posting stuff from exactly one source and that source being your employer is problematic behaviour for me, it doesn’t really matter - I like lobste.rs because it’s a communal voting system and the collective will decide the value of the content everyone posts.

                                                        1. 2

                                                          Right, but, as you note, you were not deciding based on the “value of the content” but purely on the source of the content. If you think the links I posted are not valuable based upon the content, I don’t have a problem with it being voted down.

                                                        2. 1

                                                          FTR, I feel your pain and appreciate what you are trying to do. Almost all of the articles you have posted have been full of good information, and I look forward to seeing more.

                                                          To the anti-Telerik people out there: get over your bias of the site an article is published on and try reading it before flagging.

                                                          1. 1

                                                            After first seeing you spamming Telerik articles, I spent a while googling the company (bored, obsessive, too much coffee, I can’t remember). Can you describe their business so it’s more clear, because the website is very templatey, commercial and sales-y. The stock photos make it look strange, and it is very unfriendly and unclear what the core business is.

                                                            My guess was that their business was cash driven - purchase troubled or cheap tech projects to then sell those ‘boxed’ products, grouping them together into some kind of rough collective with the hope of cross-sales, or to flip the individual companies or sell the whole thing later for a profit.

                                                            This also appears to be the strategy of the parent company Progress, who also have an extremely weird web site.

                                                            If I had $10M in the bank for a project, and I recruited someone to go out and buy little tech projects into a profitable portfolio without actually caring what they were, and get some shiny website built for the whole thing, I think Progress/Telerik is what would come out.

                                                            But, please prove me wrong, and I hope this is some feedback as to why I’m suspicious and how your behaviour fit with the notion of a heavily sales/conversion based company, and how Telerik and Progress’s website look to me.

                                                            1. 1

                                                              I hate to say it, but you seem to very much focused on making criticisms and snap judgements based purely on preconceived notions and biases and gloss over any of the actual information. You’ve already made a number of judgements about Progress and Telerik based on images and the look of the site. People do that…I get that. However you’ve taken a lot of time to criticize me and backhandedly criticize my employer, without taking even a moment (it would appear) to read anything - the article I linked to, any of the product or company information on the sites of either Progress or Telerik. And yet you call what I post spam?

                                                              1. 1

                                                                My post was a description of how these companies appear to me and a request to understand their business, so your posts can be placed in some better context

                                                        3. 1

                                                          Ah, that would make more sense, if that was indeed what he meant.

                                                  1. 1

                                                    It’s funny to see an article like this, demanding more innovation.

                                                    A few days ago we had an article telling us the web suffered from too much innovation and that a good approach would be to stop new “standards” for a couple of years.

                                                    I personally agree with the latter. Instead of clamping more and more onto it, we need to clear out the trash. Of course, you can’t ban HTML5, but as food for thought for the W3C, what’s so hard about just declaring a set of default video formats every browser should support? And as a minimal condition, these formats shouldn’t be patent-encumbered or non-free. The people at the W3C should grow some balls and finally start coming up with strict standards. It’s not helpful when they just spend their time “documenting” what the big companies have come up with in the major browsers. In the end, nobody can grasp what it’s all about and you need millions of man hours to even create a decent web-browser.

                                                    The web should be free, so why on earth are we so inclined to make it so inaccessible?
                                                    1. 5

                                                      There’s not even a list of plain image formats a browser must support, is there? Maybe start with that before trying to solve video.

                                                      1. 3

                                                        I actually thought about this point when I wrote the paragraph about video formats. Thing is, it took over a decade for browsers to properly support a set of image formats properly, and this was mostly due to a long evolutionary process where certain formats were found to be best for certain applications (jpg for photos, png for line-art, gif for animations, …), but living in Web 3.0 we forget how difficult it has been to come this way.

                                                        Nowadays, people not only understand what webm, ogg, mp4, … are really good for (and tbh, it’s all about storage size anyway) and publishing “HTML 5 video” becomes a complex task, but also companies fight wars with “their” formats. Only a fool would believe the “best” format is chosen for technical reasons in this early stage; webm is on a good way though. Apple has MPEG, Google has webm, Microsoft has/had wmv, … . Image formats never “really” belonged to a special company if we take a look at those which raced for the win a few years ago in the web.

                                                      2. 2

                                                        what’s so hard about just declaring a set of default video formats every browser should support?

                                                        A declaration is useless without incentives or consequences to back it up.

                                                        The W3C isn’t in a position to send ultimatums to Google, Microsoft, etc. Most national governments aren’t even in that position.

                                                        1. 1

                                                          Though, the W3C is definitely in a position to declare standards. That’s what it does, or am I missing something? Of course, the companies are not forced to adhere to these standards, but if the W3C for instance declared webm to be a “must-have”-supported format, maybe Apple would be more inclined to support it, else Safari would quickly be known as the “non-standard” browser. Not in the interest of being booed I guess they would do it.

                                                          However, the W3C literally is a set of representatives of the industry. I never expect them to make a move.

                                                          1. 5

                                                            Standards aren’t declared, they’re agreed-upon. It’s the only way the political dynamic can work.

                                                            if the W3C for instance declared webm to be a “must-have”-supported format, maybe Apple would be more inclined to support it, else Safari would quickly be known as the “non-standard” browser

                                                            That’s a pretty weak threat. Even if Apple cared, they could easily win any PR war because they’re popular and the W3C is not.

                                                        2. 2

                                                          The people at the W3C should grow some balls and finally start coming up with strict standards.

                                                          “Fuck the pope. How many divisions does he have, anyway?”

                                                          1. 1

                                                            Thanks for the comment. To be clear, I was pushing for a very different kind of innovation than the one PPK was arguing against. I was arguing for building fun/cool things on the web again - not on pushing more browser features. To me, the web was once fun and innovative, but has lost that edge to IoT, devices and apps.

                                                          1. 1

                                                            It hosts over 64 thousand modules and counting.

                                                            I can’t even begin to comprehend that. That’s ten times larger than the entire OpenBSD ports tree, 95% of which I have never used or even heard about.

                                                            1. 1

                                                              I wonder how many of them are re-implementations of existing modules that weren’t noticed because they had “clever” names instead of boring things like everything in CPAN.

                                                              1. 1

                                                                It is a lot. They actually introduced a new rating system to help you find the best solution.