Edits to text in Update API doc

[dmeiss]

Minor edits to text for formatting, punctuation, and word usage.

[danielmitterdorfer]

To me the changes is fine as is but I left one comment / suggestion.

[elasticmachine]

Pinging @elastic/es-distributed

[danielmitterdorfer]

@elasticmachine test this please

[danielmitterdorfer]

Looks good to me.

[dmeiss]

Hi Daniel:

General question: I'm a longtime technical editor, but I'm pretty new at using GitHub -- is there any way I should be going about this process differently? i.e., is there anything I can do that makes this easier on reviewers? I just want to make sure I'm following the rules, best practices, etc.

Thx,
D

[danielmitterdorfer]

I think your approach is totally fine. We prefer small, targeted PRs to massive ones because that makes it easier to manage (e.g. a PR that is "fixing everything that's wrong in your docs" is probably much harder to get in than one that covers specific aspects).

Personally, I find your PRs rather good and quick to review so I think you should just stick to your current approach. As you may inferred from the number of version labels that I've applied to your PRs, we need to port them to quite a few branches though because our documentation is versioned but I'd still prefer this to massive PRs which would then cause a lot of merge conflicts anyway.

At this point I also want to thank you for your contributions; that's really helpful and an immediate improvement for our entire user base.

[dmeiss]

Thanks much for the feedback. I'll keep small PRs in mind when editing some of those really long docs. I'll try to edit just a few sections at a time to keep the PR more concise.

[dmeiss]

@danielmitterdorfer
Hi Daniel:

I have another general question, if you don't mind. (I'm also not sure where to bring this up, so I just tacked this comment onto this PR.)

While editing docs, I've noticed that the link tooltips for anchor links append the word "edit" to the tooltip text, e.g. the link "Search Cancellation" has a tooltip of "Search Cancellationedit". In looking at the HTML, I can see that it's because each heading also contains the Edit icon and text, and it appears that the anchor link's title attribute is formed based off all the text in the heading tag:

<a class="xref" href="search.html#global-search-cancellation" title="Search Cancellationedit">Search Cancellation<a href="https://github.com/elastic/elasticsearch/edit/6.6/docs/reference/search.asciidoc" class="edit_me" title="Edit this page on GitHub" rel="nofollow">edit</a></a>

<h2><a id="global-search-cancellation"></a>Search Cancellation<a href="https://github.com/elastic/elasticsearch/edit/6.6/docs/reference/search.asciidoc" class="edit_me" title="Edit this page on GitHub" rel="nofollow">edit</a></h2>

It's certainly not the biggest deal in the world, but ideally the link tooltips would look much better without it.

[danielmitterdorfer]

@dmeiss thanks for the feedback. I think it's best to raise an issue so our docs team can have a look at this. Can you please create one?

[dmeiss]

@danielmitterdorfer Hi Daniel -- thanks for the response. I also posted this on the Elastic forum. Nik Everett opened an issue for it.

[danielmitterdorfer]

That's great, thanks for following up!