3 ms·

> Keycloaks documentation seems vast, but isn't. There is also no way to search inside their documentation. This is one area where incentives don't align corre

> Keycloaks documentation seems vast, but isn't. There is also no way to search inside their documentation. This is one area where incentives don't align correctly for open source projects that offer commercial support.

freedomben 5y ago
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.
- password4321 5y ago
  Thank you for taking the time to share your first-hand perspective!
- _jal 5y ago
  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.
  - pas 5y ago
    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?
    - freedomben 5y ago
      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.
  - freedomben 5y ago
    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.
- yencabulator 5y ago
  Isn't the existence of separate RH product docs (that require log in) a validation of the parent's point?
deleted 5y ago
[deleted]
smcnally 5y ago
> This is one area where incentives don't align correctly for open source projects that offer commercial support. This is true in some[0] cases. It's also true that documentation is key source of customer acquisition and retention. Projects get traction by making it useful out of the box[1] for some use-cases, making it appealing for hackers to config and extend, teasing features the former would pay for and the latter could figure out the buy v build. Projects that do this well also learn shittons from real-world usage and feedback informing their roadmap and new opportunities to pursue. [0] True when the perspective is "If we make the docs too good we're losing revenue" / "Everyone using Feature X gratis is a loss in MRR." It's an understandable view that's held widely. It's not often a significant revenue factor in my experience, and ~never when accounting for product and market insights gained by wider adoption. [1] https://news.ycombinator.com/item?id=31259034 https://news.ycombinator.com/item?id=31259034

freedomben 5y ago

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.

password4321 5y ago
Thank you for taking the time to share your first-hand perspective!
_jal 5y ago
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.
- pas 5y ago
  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?
  - freedomben 5y ago
    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.
- freedomben 5y ago
  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.
yencabulator 5y ago
Isn't the existence of separate RH product docs (that require log in) a validation of the parent's point?

deleted 5y ago

[deleted]

smcnally 5y ago

> This is one area where incentives don't align correctly for open source projects that offer commercial support. This is true in some[0] cases. It's also true that documentation is key source of customer acquisition and retention. Projects get traction by making it useful out of the box[1] for some use-cases, making it appealing for hackers to config and extend, teasing features the former would pay for and the latter could figure out the buy v build. Projects that do this well also learn shittons from real-world usage and feedback informing their roadmap and new opportunities to pursue. [0] True when the perspective is "If we make the docs too good we're losing revenue" / "Everyone using Feature X gratis is a loss in MRR." It's an understandable view that's held widely. It's not often a significant revenue factor in my experience, and ~never when accounting for product and market insights gained by wider adoption. [1] https://news.ycombinator.com/item?id=31259034 https://news.ycombinator.com/item?id=31259034