4 ms·

Indeed. ElasticSearch is super useful, but its docs used to be of the frustrating variety: "Explain minute API details, as if a passing note from the lead dev

by Radim 12y ago

Indeed. ElasticSearch is super useful, but its docs used to be of the frustrating variety: "Explain minute API details, as if a passing note from the lead dev to himself, assuming all context and concepts are understood and obvious. Don't bother with why's & what's & high-level nonsense." It's been improving lately though, "going big" helped ES here. My personal favourite: an issue from 3 years ago, where ElasticSearch returns incorrect facet counts (as in, fundamentally BROKEN faceting). Still unresolved: https://github.com/elasticsearch/elasticsearch/issues/1305 https://github.com/elasticsearch/elasticsearch/issues/1305

capkutay 12y ago
but its docs used to be of the frustrating variety I hope this doesn't sound like a knock on open source technology, but when a company's only revenue stream is providing training and support for an open source framework, doesn't writing laconic documentation seem to be in their interest?
- stingraycharles 12y ago
  That depends on how you look at it. A short-sighted manager might think that way, but it will hurt (early) adoption / engagement. The target audience for big support contracts are enterprises anyway, and they will not buy support solely for the documentation.
  - capkutay 12y ago
    These guys win early engagement by being free and having awesome functionality. Want to tune it to actually work for your needs? Trying to figure out how to use our 'RAMOptimization' library? Better start buying some training!
- michaelt 12y ago
  Equally, if a company's only revenue stream is paid upgrades, doesn't that mean releasing software in urgent need of upgrading, with bugs and poor forward-compatibility is in their interests? And if a company's only revenue stream is monthly or annual subscriptions, doesn't that mean firing all the developers and letting the product stagnate as money keeps flowing in is in their interests?

by Radim 12y ago

capkutay 12y ago

but its docs used to be of the frustrating variety I hope this doesn't sound like a knock on open source technology, but when a company's only revenue stream is providing training and support for an open source framework, doesn't writing laconic documentation seem to be in their interest?

stingraycharles 12y ago
That depends on how you look at it. A short-sighted manager might think that way, but it will hurt (early) adoption / engagement. The target audience for big support contracts are enterprises anyway, and they will not buy support solely for the documentation.
- capkutay 12y ago
  These guys win early engagement by being free and having awesome functionality. Want to tune it to actually work for your needs? Trying to figure out how to use our 'RAMOptimization' library? Better start buying some training!
michaelt 12y ago
Equally, if a company's only revenue stream is paid upgrades, doesn't that mean releasing software in urgent need of upgrading, with bugs and poor forward-compatibility is in their interests? And if a company's only revenue stream is monthly or annual subscriptions, doesn't that mean firing all the developers and letting the product stagnate as money keeps flowing in is in their interests?