Ecs: Adjustments to the field set "usage" docs

[webmat]

Capturing thoughts while working on #1066.

• [x] #1345 Make the callout to usage stand out more

The call out to the usage section -- under the field set description -- looks like just one more line in the normal description. We should make it stand out more. Example:

• [x] #1345 Rephrase the callout a bit

Currently: Find additional usage and examples in the [field set shortname] fields usage section.

Suggested: TBD, in the context of making it stand out more.

• [x] Normalize the page name in the sidebar

Right now the sidebar link is based on the page heading.

I'd like to ensure the sidebar has a regular look, regardless of the heading we put on each page. We should override the sidebar link text to <<...,Usage>>.

[djptek]

@ebeahan I'm not sure how to interpret

I'd like to ensure the sidebar has a regular look, regardless of the heading we put on each page. We should override the sidebar link text to <<...,Usage>>.

[ebeahan]

When a usage doc is added, it also adds another nested level under the field set it's associated with in the docs:

The title of the usage doc will also be used as the name in the sidebar. If I wanted to hypothetically name my usage doc "Something Else" for the URL fieldset:

[[ecs-url-usage]]
==== Something Else
...

It would generate in the docs as:

I think the intent here is to have the sidebar always use "Usage" for the usage docs links and not the title of the usage doc itself.

[djptek]

OK, thanks for the extensive clarification @ebeahan, since it's already called Usage I wasn't clear on why there was an ask to rename to Usage - point is to ensure that's a rule not a manual process, got it.

I've taken a look through a sample of other Elastic docs to how we frame Usage and from my limited research I don't see a case for using the word Usage in isolation , here are two examples with more verbose link names.

https://www.elastic.co/guide/en/elasticsearch/client/net-api/7.x/pipeline-aggregations.html

https://www.elastic.co/guide/en/elasticsearch/reference/7.x/_api_usage.html

During this (brief) search I couldn't find any examples of "Usage" as a single word title, the standard would appear to be more verbose titles, which may also be advantageous when locating content via the search box.

So, I'm inclined to actually suggest the opposite - that the Usage page be named User Field Usage and Examples.

Also, I think the Usage page has other issues, for example, the opening sentence Here are the subjects covered in this page. and use of the word elided which, while perfectly correct, is not plain English.

I'll submit the PR for the fixes to the callout from the User Fields page in it's current state https://github.com/elastic/ecs/pull/1345 with no changes to the Usage page pending clarification of verbose titles and potentially other rework to the latter.

[kgeller]

@djptek I really like your suggested rename. And I think the mentioned tweaks to the page as a whole would be nice to help sharpen things up a bit.

[djptek]

PR & Backport merged here:

1345

and here:

1353

Can we close this issue?

[ebeahan]

Thanks for the work in #1345!

Let's keep this open until we finalize an approach with the sidebar. I've edited the original description showing we've completed two of three adjustments so far.

So, I'm inclined to actually suggest the opposite - that the Usage page be named User Field Usage and Examples.

I like this more verbose naming as well. I do still see value in trying to ensure there's consistency in the sidebar.

The way usage docs are folded into the rest of the ECS documentation is by using the include asciidoc directive:

include::usage/user.asciidoc[]

Then include uses the section title from the usage doc page to generate the link in the sidebar:

[[ecs-user-usage]]
==== Usage

Maybe we do a quick investigation to see if anything AsciiDoc can do to ensure consistency, but I don't think it's something we invest much time into.

I think it's an acceptable alternative to document our convention (say that we decide on $fieldsetName Field Usage and Examples) in the usage docs README. WDYT?

If we do the latter, it'll just be an item we keep in mind when writing/reviewing feature usage doc contributions.

Also, I think the Usage page has other issues, for example, the opening sentence Here are the subjects covered in this page. and use of the word elided which, while perfectly correct, is not plain English.

For these or any other possible improvements you come across, feel free to open an issue and/or PR so we can address them.

[djptek]

Maybe we do a quick investigation to see if anything AsciiDoc can do to ensure consistency, but I don't think it's something we invest much time into.

this was trivial in templates/field_details.j2 so I did that, but I didn't see an equivalent solution for docs/usage/user.asciidoc so there I edited directly and added upstream guidance to establish the convention in the associated docs/usage/README.md

I am not super-keen on the text Here are the subjects covered in this page., however, the page starts with a Table-of-Contents, so there should be something between that and the title: I gave this sufficient thought and I don't have a better idea so I would suggest to leave this as is.

I've opened a PR https://github.com/elastic/ecs/pull/1354

[djptek]

Here's a quick screenshot of how #1354 looks

[djptek]

1354 merged and closed