Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

User's Guides covering major usecases and sample code for all Clients #56

Open
4 of 7 tasks
nhtruong opened this issue Mar 27, 2023 · 2 comments
Open
4 of 7 tasks
Labels
enhancement New feature or request

Comments

@nhtruong
Copy link

nhtruong commented Mar 27, 2023

As brought up in this issue, to help drive adoption of OpenSearch, and improve user's experience, we're working on adding more documentation for all clients. One of the strategies mentioned in said issue is writing a collection of articles serving as a User's Guide for each client. This issue will serve as a hub for all issues related to this topic. The hub will keep track of the progress and assure that every repo has a consistent set of articles.

Conventions

  • All articles will be written in markdown (.md) and stored in guides folder at the root of each repo.
  • The file names and article titles must be identical to what stated in the "Topics" section below. Each article must also include all endpoints listed (They don't have to be of the same order and other unlisted endpoints can be included if necessary).
  • Each code block must be explicitly delineated with the language it's written in. For example, a javascript code block must start with ```javascript instead of just ```
  • Pieces of code that are expected to throw errors, say you want to demonstrate that you cannot create a document of the same ID, must be wrapped in try/catch or rescue blocks. That is all code blocks in a guide must be able to be executed in order without throwing any errors.
  • Each article must have the following sections:
    • Introduction: An Overview of the Guide/Tutorial
    • Setup: Specify what's required before running the sample code. This should include code blocks, if any, that setup the stage. For example, article on "Document Lifecycle" should have a code block instantiating a client instance and creating an OpenSearch index.
    • Endpoint Sample Code: This is the meat of each article where we demonstrate how the endpoints are used for each client.
    • Clean Up: Remove all artifacts created by the guide.

Topics

Below is a list of topic titles, file names, link to the Ruby version of each guide, along with the endpoints that they cover.
More topics will be added over time. Feel free to suggest new topics in the comment.

  • Index Lifecycle (index_lifecycle.md):
    • Create index
    • Index exists
    • Get Index Settings
    • Update Index Settings
    • Delete index
  • Advanced Index Actions (advanced_index_actions.md):
    • Clear Index Cache
    • Open / Close Index
    • Clone / Split / Shrink Index
  • Index Template (index_template.md)
    • Create/Update Templates
    • Get Templates
    • Delete Templates
    • Composable Templates
  • Document Lifecycle (document_lifecycle.md):
    • Index document
    • Reindex document
    • Get document
    • Multi-get document
    • Update document
    • Update by query
    • Delete document
    • Delete by query
  • Search (search.md):
    • Basic Search
    • Pagination
    • Scroll
    • Point-in-time
  • Bulk (bulk.md):
    • Bulk Create
    • Bulk Index
    • Bulk Update
    • Bulk Delete
@nhtruong nhtruong added enhancement New feature or request untriaged labels Mar 27, 2023
@dblock
Copy link
Member

dblock commented Mar 27, 2023

  • I'm glad to see us improve docs!
  • I think guides is unusual, how about docs?
  • lifecycle is one word
  • I think we need a markdown linter

@nhtruong
Copy link
Author

@dblock regarding docs, we're already using it for method documentation in a few repos. Plus these articles will be referenced in USER_GUIDE.md as extensions to the base guide.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
enhancement New feature or request
Projects
None yet
Development

No branches or pull requests

3 participants