search

opensearch-project / opensearch-php

Official PHP Client for OpenSearch
Other
98 stars 55 forks source link

[FEATURE] Documentation is lacking #46

Open jonkerw85 opened 2 years ago

jonkerw85 commented 2 years ago

Is your feature request related to a problem? Documentation is lacking regarding migration path and usage.

What solution would you like? Provide the following information

What alternatives have you considered? I'm proviant enough to do the migration without assistance and use the ElasticSearch-PHP documentation as a reference.

Do you have any additional context? Look at the ElasticSearch documentation it is great in al regards

shyim commented 2 years ago

Hey,

yea you are right. The basic user guide can be found here https://github.com/opensearch-project/opensearch-php/blob/main/USER_GUIDE.md

stormrockwell commented 2 years ago

Better documentation would be great instead of needing to dive into the source for everything. Compared to ElasticSearch's documentation, it's lackluster.

jeffkarney commented 2 years ago

Ya it would really be nice if a multi-billion dollar company could spend a few dollars to write a few docs for something they copied. This library is essentially useless at this point.

When the few examples say "Do not do this in production", but have absolutely no documentation or references to any other methods seems to point at the fact that AWS just doesn't care to support what they copied.

shyim commented 2 years ago

Hey,

I am not working for Amazon and doing this in my free time. What exactly is missing from your point?

I looked into the Elasticsearch and saw missing things:

I would say none of them are really blocking to onboard a new developer. As the users look mostly directly in the REST documentation and find then the PHP method to execute it using the parameter, I would say it works okayish.

What I want to work on is to use array shapes like the async-aws library to have better autocompletion in the IDE for the parameters

jeffkarney commented 2 years ago

Ok, got it! My apologies for just assuming this was created by or financially backed by Amazon / AWS. This library definitely saved me time, however I did still have to dig into things a lot, but I am also 100% new to OpenSearch and Elasticsearch. So there was a learning curve no matter what.

I'll get together some more constructive feedback and maybe will open some other issues so I don't get this one off topic. Hopefully I can help a bit too. Besides the lack of documentation outside of the code, the big issue for me was mostly just finding classes and functions. The layout of the library seems a little strange and has issues with code completion. But sounds like you already know that and are hoping to work on it.

In general, it might make sense to add some clarification with how this specific project relates to Amazon/AWS and OpenSearch. Sure OpenSearch is open source, but it is really just an AWS service for most people at this point. Maybe that will change in the future, but I don't think many would select it as a solution if they aren't specifically using it on AWS at this point in time.

With that being said, I think the main thing any potential contributors and users would want to know is... is this a library simply meant to be a fork of the Elasticsearch version? Or is the intention to make it its own thing as it evolves?

Knowing that will sort of help me know what I think might be missing in documentation and/or functionality.

saimedhi commented 4 months ago

Hello @jonkerw85, @jeffkarney, @shyim, @stormrockwell,

I agree that we need to enhance the documentation for the OpenSearch-PHP client.

What further steps do you think we should take to improve the documentation? Let's collaborate to make the documentation better.

Thank you.