[API]: Text and titles in Machine Learning Kibana API docs is unnecessarily verbose

[peteharverson]

Was the documentation helpful?

Yes

What documentation page is affected

• https://www.elastic.co/docs/api/doc/kibana/operation/operation-mlsync

Description

The text and titles on the docs pages for the public Machine Learning API docs is overly verbose and would benefit from a review to make it more concise, and consistent with the style used on other pages.

For example Sync saved objects in the default space

• Drop in the default space from the title Sync saved objects in the default space.
• Response attribute datafeedsAdded text - could be simplified to something like Contains a list of datafeed objects that were identified for addition as a result of synchronization.
• Response attributes datafeedsRemoved, savedObjectsCreated, savedObjectsDeleted - similar approach needed as for datafeedsAdded above.

cc @nastasha-solomon

[nastasha-solomon]

The following notes apply to serverless and stack API docs.

GET /api/ml/saved_objects/sync

https://www.elastic.co/docs/api/doc/kibana/operation/operation-mlsync

Item	Current	Suggested	Justification
summary	Sync saved objects in the default space	Sync saved objects	The endpoint supports all spaces via {space_id} in the path, so "in the default space" is both misleading and redundant.
description (opening sentence)	Synchronizes Kibana saved objects for machine learning jobs and trained models in the default space.	Synchronizes Kibana saved objects for machine learning jobs and trained models.	Removes "in the default space" for the same reason as the summary.
datafeedsAdded (response attr)	The sync machine learning saved objects API response contains this object when there are datafeeds affected by the synchronization. There is an object for each relevant datafeed, which contains the synchronization status.	Datafeed objects identified for addition during synchronization, keyed by datafeed ID. Each object contains the sync status.	Self-referential and wordy. Revised text describes the data structure accurately (it's a keyed map, not a list) at under half the length.
datafeedsRemoved (response attr)	The sync machine learning saved objects API response contains this object when there are datafeeds affected by the synchronization. There is an object for each relevant datafeed, which contains the synchronization status.	Datafeed objects identified for removal during synchronization, keyed by datafeed ID. Each object contains the sync status.	Same issues as datafeedsAdded.
savedObjectsCreated (response attr)	If saved objects are missing for machine learning jobs or trained models, they are created when you run the sync machine learning saved objects API. [Same self-referential pattern as datafeeds attributes]	Saved objects created during synchronization, grouped by job type. Each entry contains the sync status per job ID.	"Grouped by job type" is more precise than "list of". The response nests job IDs under a type key (e.g. anomaly-detector).
savedObjectsDeleted (response attr)	If saved objects exist for machine learning jobs or trained models that no longer exist, they are deleted when you run the sync machine learning saved objects API. [Same self-referential pattern as datafeeds attributes]	Saved objects deleted during synchronization, grouped by job type. Each entry contains the sync status per job ID.	Parallel structure with savedObjectsCreated. "Deleted" replaces "created"; no other changes needed.

POST /api/ml/saved_objects/update_jobs_spaces

https://www.elastic.co/docs/api/doc/kibana/operation/operation-mlupdatejobsspaces

Item	Current	Suggested	Justification
summary	Update jobs spaces	Update job spaces	"Jobs spaces" reads as a noun pile. Singular "job" follows standard Kibana API title convention and removes the ambiguity of whether "jobs" is a possessive or a compound modifier.
description (body text)	Update a list of jobs to add and/or remove them from given spaces.	Updates the spaces that one or more jobs are assigned to.	"A list of" is implied by the array parameter. "And/or" is informal. "Given spaces" is vague.
jobType (request body — no description present)	—	The type of job. Supported values are anomaly-detector and data-frame-analytics.	The two valid values are only revealed in examples. Explicit enumeration in the description makes the field self-documenting.
spacesToAdd (request body — no description present)	—	The spaces to assign the jobs to.	Missing description. Mirrors the parameter name with plain language.
spacesToRemove (request body — no description present)	—	The spaces to remove the jobs from. Use * to remove from all spaces.	The wildcard * behavior is visible in examples but not documented. Noting it here means users don't have to infer it from example values.

POST /api/ml/saved_objects/update_trained_models_spaces

https://www.elastic.co/docs/api/doc/kibana/operation/operation-mlupdatetrainedmodelsspaces

Item	Current	Suggested	Justification
summary	Update trained models spaces	Update trained model spaces	Same noun-pile issue as "Update jobs spaces". Singular "model" is consistent with the suggested fix for the jobs endpoint.
description (body text)	Update a list of trained models to add and/or remove them from given spaces.	Updates the spaces that one or more trained models are assigned to.	Parallel structure with the suggested fix for the jobs endpoint. Removes "a list of", "and/or", and "given spaces" for the same reasons.
spacesToAdd (request body — no description present)	—	The spaces to assign the trained models to.	Missing description. Mirrors the suggested text for the jobs endpoint with "trained models" substituted.
spacesToRemove (request body — no description present)	—	The spaces to remove the trained models from. Use * to remove from all spaces.	Same wildcard documentation gap as the jobs endpoint.

[nastasha-solomon]

@jgowdyelastic handing this off to you since devs own the OAS specs/API docs. Feel free to ping me if there's more to review.

[nastasha-solomon]

Keeping open as I might need to review the doc updates coming from this issue. Moving to the next sprint so I can still track this task.

[nastasha-solomon]

Closing since the primary task is done.