Hacker News Reader

Comment by streblo | Hacker News Reader

> Ask where the documentation is.

I've had a reasonably long career and worked at a number of companies at this point, and I've never seen this 'documentation' that engineers are supposedly producing.

View on HN

I think existence of documentation is a poor metric, personally.

I think a better metric is to ask why the documentation isn't better. Nobody is ever happy with their documentation, whether they have too little or too much. But if the engineers think it's because they're being pushed too hard and there's no slack time available to write docs? Red flag. They have explicitly considered the question and realized that the effort to write the docs, compounded by the need to keep them up to date and/or the cost of allowing them to be out of date, is not worth it in their particular situation? Good sign. They feel kind of bad and guilty about the state of the docs? Too normal to be much of a sign, but still positive.

These questions are ultimately just asking what the work culture is like, they don't really have anything to do with documentation. And in that sense they're good questions to ask during an interview. As you allude to though, I don't think you're going to get good information if you just ask surface level questions about docs.

The meat of the question is, "where do you go when don't know how to do a thing?".

The answer could potentially be "the docs", but that's not necessarily sufficient like you point out. However, you could ask follow-ups, e.g., whether the docs have multiple facets like user guides in addition to low-level API guides.

OTOH, where you go when don't know how to do something doesn't necessarily have to be the docs, and info here can still be valuable to understand. E.g., are questions typically discussed in public forums or is it discussed in private DMs? The former is typically a better signal in my experience.

Compare the quality in the documenation from lawyers and engineers in the company. True experts tend to be excellent communicators. SJ adequately described the short comings of Flash the phoneys pushed back against without merit.

We really have the opposite problem, there are lots of documentations but they are not exactly organized or all up to date. Much easier to fix than not having any of them I would guess.

I feel like having too much doc is not really a problem :)

Welcome to health care. We produce a ton of documents that then disappear into a terrible document management system to never be found again.

Reply on news.ycombinator.com