NEST 2.X Documentation Lacks a "Core" Section

[tveyes-user]

The documentation for NEST 1.X includes an incredibly helpful section titled "Core". This section gives simple examples of the various basic use cases of NEST.

The documentation for NEST 2.X lacks this important section. At present if you want to learn how to perform basic tasks (index, get, update or delete) you have to search through the tests.

I think this is an important omission and should be resolved.

Thanks very much!

-D

[russcam]

Hey @tveyes, thanks for raising this. The documentation for 2.x is very much a work in progress but it is a lower priority at the moment compared to getting an Elasticsearch 5.0 compatible client ready, as well as adding all of the new features that have come in 2.3.0+.

I've added the Up For Grabs label to this if anyone would like to tackle it in the meantime?

All documentation is generated from code within the Tests project; For examples like this, the files should be *.doc.cs files with a class and set of methods to demonstrate each of the features. The documentation around each method is wrapped in a multi-line comment and adheres to the asciidoc format. Take a look at the Automap source and documentation as an example. Ideally, each method should be a runnable unit/integration test but I think this is not so important here as these are purely for documentation purposes and repeat functionality covered in other tests.

Once the docs are there, running Nest.Litterateur will generate the final asciidoc from the *.doc.cs file and place it in the docs directory in the root. The last part is including it with the rest of the docs. These files are then picked up by the elastic docs generator.

[ahazelwood]

I would also second this as trying to figure out how to do things that used to be fairly simple, like MoreLikeThis queries are a chore to figure out. Having the ability to show samples using the query dsl would go a long way towards bringing new users on board more quickly.

[Mpdreamz]

closing this in favor of new tracking issue: #2248