[Novashi]

False dichotomy, and if you actually witness this first hand and only have two options in your candidate pool, you might need to spread your net a bit further. Also the original post was about READMEs only, so if they have unmaintainable code, the README really doesn't matter that much, does it?

Developers are at various stages in their expertise when they go looking for jobs. READMEs are nice but try not to let yourself get tied up with emphasis on a few signals that document the whole human. README quality is a pretty weak signal.

If you bring up the README in an interview, and the dev cannot find any motivation or acknowledge that it could be better, then maybe you might have to pass on them. My problem with your methods is that you get to this point without even opening a discussion.

READMEs are a relatively teach-able skill and in pretty quick fashion. Maintainable code, much less so obviously.

[zepolen]

> README quality is a pretty weak signal.

It's a fantastic signal of what the quality of the code will be. Lack of a README indicates many things, including unmaintainable code either via lack of experience or rushed work.

But hey talk is cheap and you seem to know a lot - so how about you link an open source project you've published ;)

[dang]

That crosses into personal attack, which is a bannable offense on HN. Please don't do this.

https://news.ycombinator.com/newsguidelines.html

[Novashi]

>But hey talk is cheap and you seem to know a lot - so how about you link an open source project you've published ;)

I wrote tech docs explaining the jungle of IT systems that we were relying on at a hospital I worked at, and sometimes that included diving into old code. These were usually much longer than READMEs.

Having a README wouldn't have saved this code from needing to be refactored. Nor would it have really changed my opinion of the code. It hasn't been a reliable signal.

The hard part about documentation is keeping it up-to-date and accurate and not filling it with extraneous details and going off on tangents. A lot of the READMEs are written for quick bootstrapping and that isn't going to reflect much on your code quality. I care more about good documentation and that's harder to write than a README and a much better signal.

I don't have time to work on open source but it's clear my experience has been vastly different than yours and I doubt either one of us are going to come up with a peer reviewed reason for either side.

Turn this around and say "this repo has a README! surely it's really good and so is the code" and it makes no sense to give that much credit for something that really isn't impactful beyond the first few days of using something.

[zepolen]

A programmer who by default adds a good concise readme to his projects is an indicator that the same will apply to the codebase, in that he will plan for the future.

I've seen it too many times, exceptions are rare.

A good readme is concise, it offers key 'bring me up to speed as fast as possible' information, nothing more. It's not documentation.

A good readme should include a quick bootstrapping info, but it's not enough, it should have a concise summary overview and list any important gotchas. As well as provide the procedures for builds/releases if apply. Links to relevant docs if exist are fine if the information becomes too large for the readme.

> Having a README wouldn't have saved this code from needing to be refactored. Nor would it have really changed my opinion of the code. It hasn't been a reliable signal.

See I read that and figure that it was actually a perfect signal - since that "bad unmaintainable code" lacked a good readme.

It's like the Van Halen requiring Brown M&Ms at their concerts https://www.snopes.com/fact-check/brown-out/ - I've found the README is one of the best indicators of the level of detail a person applies to their work.

> it makes no sense to give that much credit for something that really isn't impactful beyond the first few days of using something.

This is the attitude that I wouldn't be looking for when recruiting - a README has a ton of use, for helping bootstrapping new people to the code base - to even helping yourself if you do some maintenance on an old project and don't want to spend more than the minimum time necessary.

It's this forethought I'd like to see in a candidate, and that 99.9% of the time shows in the quality of the readme.