[FEATURE] Documentation is lacking

[jonkerw85]

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

• How to migrate from the ElasticSearch-PHP library to OpenSearch-PHP Library (like composer and changed namespaces)
• How to execute a simple query with OpenSearch-PHP
• Provide (on another place then Github?) more in-depth information about this library.

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]

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]

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

[jeffkarney]

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]

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:

• Logger configuration
• Hosts configuration
• Namespace overview

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]

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]

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

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

• I believe adding the guides mentioned here would partially address this issue.
• Additionally, there is an ongoing effort to make the client generatable from the specifications in the opensearch-api-specification repo. This will help in adding API descriptions and parameter descriptions for all APIs. Relevant issue: [FEATURE] New API Client generated from spec #97

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

Thank you.