Hacker Newsnew | past | comments | ask | show | jobs | submitlogin

Disclaimer: Former Red Hatter but worked on OpenShift, not Keycloak

Working as a person providing commercial support for open source projects, I promise it doesn't actually work that way. Incentives are entirely for creating good documentation. Having crappy docs only hurts project adoption for paying and non-paying customers, increases the support burden, and wastes the time of your employees (who are the primary consumers of that documentation).

Usually documentation isn't great because writing (and maintaining!) good documentation is really hard. It's a continual effort and it takes engineer time away from bug fixes and feature dev, two things for which there is never ending demand for.

Edit: Pro-Tip: With Red Hat projects (like Keycloak, OKD, etc) it's always worth looking at the RH product docs as well as "open source" docs. For example if you use OKD, check OpenShift docs as well as OKD docs. You do (unfortunately and I wish they'd remove this) usually have to log in to a Red Hat account but you don't have to pay. You can create a free account and use that.



I can tell you that at least as of late last year, the OpenShift install docs omitted key details for setting it up.

We were unable to do so until contacting RH and getting additional instructions - I forget the all the details, part of it involved creating DNS records mentioned nowhere in the docs.


If you can remember which ones, I'd be interested. I installed OpenShift a dozen or so times using those docs and I don't remember having to add any DNS records that weren't in the docs. I also grepped my notes and don't see anything. That said I do remember the DNS records being on a page that wasn't the one I thought it should be on.

Something I do criticize them for though (this is a problem in broader tech not just Red Hat) is that they are aggressive at culling/cutting old docs. The idea is to keep the docs small and relevant, but unfortunately in my opinion they cut valuable stuff. I always screen grab/print docs at the time in case they get removed because that's been a wide problem.


How open is OpenShift? Is there a bug where this is tracked and are people contributing at least through issue comments? And response from committers?


If you have a Red Hat subscription for OpenShift, then yes.

Although, unless it's high priority (like it's breaking functionality and there's no workaround) it's not usually a quick turnaround because it has to get prioritized and added to a sprint. It can take weeks or months. Although I did have a high-pri item fixed in under a day, so it does happen.


Isn't the existence of separate RH product docs (that require log in) a validation of the parent's point?


Thank you for taking the time to share your first-hand perspective!




Guidelines | FAQ | Lists | API | Security | Legal | Apply to YC | Contact

Search: